Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-26 09:46:32 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Updated HTML docs.

Browse source
This commit is contained in:
Evennia docbuilder action 2022-11-23 20:20:36 +00:00
parent a6076aff42
commit 64849b32e2
146 changed files with 1903 additions and 2426 deletions
Download patch file Download diff file Expand all files Collapse all files

123
docs/1.0-dev/Howtos/Tutorial-Coordinates.html
View file

@ -6,7 +6,7 @@
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Coordinates &#8212; Evennia 1.0-dev documentation</title>
<title>Adding room coordinates to your game &#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>
@ -17,8 +17,8 @@
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Dynamic In Game Map" href="Dynamic-In-Game-Map.html" />
<link rel="prev" title="Weather Tutorial" href="Weather-Tutorial.html" />
<link rel="next" title="Show a dynamic map of rooms" href="Tutorial-Displaying-Room-Map.html" />
<link rel="prev" title="Adding Weather messages to a Room" href="Tutorial-Weather-Effects.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -30,14 +30,14 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Dynamic-In-Game-Map.html" title="Dynamic In Game Map"
<a href="Tutorial-Displaying-Room-Map.html" title="Show a dynamic map of rooms"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Weather-Tutorial.html" title="Weather Tutorial"
<a href="Tutorial-Weather-Effects.html" title="Adding Weather messages to a Room"
accesskey="P">previous</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-1"><a href="Howtos-Overview.html" accesskey="U">Tutorials and Howto’s</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Coordinates</a></li>
<li class="nav-item nav-item-this"><a href="">Adding room coordinates to your game</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
@ -62,26 +62,25 @@
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Coordinates</a></li>
<li><a class="reference internal" href="#adding-room-coordinates-in-your-game">Adding room coordinates in your game</a><ul>
<li><a class="reference internal" href="#">Adding room coordinates to your game</a><ul>
<li><a class="reference internal" href="#coordinates-as-tags">Coordinates as tags</a></li>
<li><a class="reference internal" href="#some-additional-searches">Some additional searches</a><ul>
<li><a class="reference internal" href="#finding-one-room">Finding one room</a></li>
<li><a class="reference internal" href="#finding-several-rooms">Finding several rooms</a></li>
<li><a class="reference internal" href="#an-example">An example</a></li>
<li><a class="reference internal" href="#to-conclude">To conclude</a></li>
</ul>
</li>
<li><a class="reference internal" href="#to-conclude">To conclude</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Weather-Tutorial.html"
title="previous chapter">Weather Tutorial</a></p>
<p class="topless"><a href="Tutorial-Weather-Effects.html"
title="previous chapter">Adding Weather messages to a Room</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Dynamic-In-Game-Map.html"
title="next chapter">Dynamic In Game Map</a></p>
<p class="topless"><a href="Tutorial-Displaying-Room-Map.html"
title="next chapter">Show a dynamic map of rooms</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -112,18 +111,14 @@
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="coordinates">
<h1>Coordinates<a class="headerlink" href="#coordinates" title="Permalink to this headline"></a></h1>
</section>
<section class="tex2jax_ignore mathjax_ignore" id="adding-room-coordinates-in-your-game">
<h1>Adding room coordinates in your game<a class="headerlink" href="#adding-room-coordinates-in-your-game" title="Permalink to this headline"></a></h1>
<p>This tutorial is moderately difficult in content. You might want to be familiar and at ease with
some Python concepts (like properties) and possibly Django concepts (like queries), although this
tutorial will try to walk you through the process and give enough explanations each time. If you
don’t feel very confident with math, don’t hesitate to pause, go to the example section, which shows
a tiny map, and try to walk around the code or read the explanation.</p>
<p>Evennia doesn’t have a coordinate system by default. Rooms and other objects are linked by location
and content:</p>
<section class="tex2jax_ignore mathjax_ignore" id="adding-room-coordinates-to-your-game">
<h1>Adding room coordinates to your game<a class="headerlink" href="#adding-room-coordinates-to-your-game" title="Permalink to this headline"></a></h1>
<aside class="sidebar">
<p class="sidebar-title">The XYZGrid </p>
<p>See also the <a class="reference internal" href="../Contribs/Contrib-XYZGrid.html"><span class="doc std std-doc">XYZGrid contrib</span></a>, which adds coordinate support and pathfinding.</p>
</aside>
<p>This tutorial is moderately difficult in content. You might want to be familiar and at ease with some Python concepts (like properties) and possibly Django concepts (like queries), although this tutorial will try to walk you through the process and give enough explanations each time. If you don’t feel very confident with math, don’t hesitate to pause, go to the example section, which shows a tiny map, and try to walk around the code or read the explanation.</p>
<p>Evennia doesn’t have a coordinate system by default. Rooms and other objects are linked by location and content:</p>
<ul class="simple">
<li><p>An object can be in a location, that is, another object. Like an exit in a room.</p></li>
<li><p>An object can access its content. A room can see what objects uses it as location (that would
@ -137,14 +132,8 @@ instance.</p>
<h2>Coordinates as tags<a class="headerlink" href="#coordinates-as-tags" title="Permalink to this headline"></a></h2>
<p>The first concept might be the most surprising at first glance: we will create coordinates as
<a class="reference internal" href="../Components/Tags.html"><span class="doc std std-doc">tags</span></a>.</p>
<blockquote>
<div><p>Why not attributes, wouldn’t that be easier?</p>
</div></blockquote>
<p>It would. We could just do something like <code class="docutils literal notranslate"><span class="pre">room.db.x</span> <span class="pre">=</span> <span class="pre">3</span></code>. The advantage of using tags is that it
will be easy and effective to search. Although this might not seem like a huge advantage right now,
with a database of thousands of rooms, it might make a difference, particularly if you have a lot of
things based on coordinates.</p>
<p>Rather than giving you a step-by-step process, I’ll show you the code. Notice that we use
<p>So, why not attributes, wouldn’t that be easier? It would. We could just do something like <code class="docutils literal notranslate"><span class="pre">room.db.x</span> <span class="pre">=</span> <span class="pre">3</span></code>. The advantage of using tags is that it will be easy and effective to search. Although this might not seem like a huge advantage right now, with a database of thousands of rooms, it might make a difference, particularly if you have a lot of things based on coordinates.</p>
<p>Rather than giving you a step-by-step process, We’ll show you the code. Notice that we use
properties to easily access and update coordinates. This is a Pythonic approach. Here’s our first
<code class="docutils literal notranslate"><span class="pre">Room</span></code> class, that you can modify in <code class="docutils literal notranslate"><span class="pre">typeclasses/rooms.py</span></code>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in typeclasses/rooms.py</span>
@ -227,12 +216,7 @@ The <code class="docutils literal notranslate"><span class="pre">tags.get</span>
<li><p>We convert the value to an integer, if it’s a <code class="docutils literal notranslate"><span class="pre">str</span></code>. Remember that tags can only contain <code class="docutils literal notranslate"><span class="pre">str</span></code>,
so we’ll need to convert it.</p></li>
</ol>
<blockquote>
<div><p>I thought tags couldn’t contain values?</p>
</div></blockquote>
<p>Well, technically, they can’t: they’re either here or not. But using tag categories, as we have
done, we get a tag, knowing only its category. That’s the basic approach to coordinates in this
tutorial.</p>
<p>So can Tags contain values? Well, technically, they can’t: they’re either here or not. But using tag categories, as we have done, we get a tag, knowing only its category. That’s the basic approach to coordinates in this tutorial.</p>
<p>Now, let’s look at the method that will be called when we wish to set <code class="docutils literal notranslate"><span class="pre">x</span></code> in our room:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="nd">@x</span><span class="o">.</span><span class="n">setter</span>
<span class="k">def</span> <span class="nf">x</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
@ -249,19 +233,15 @@ tutorial.</p>
room with “coordx” as their category, which wouldn’t do at all.</p></li>
<li><p>Then we add the new tag, giving it the proper category.</p></li>
</ol>
<blockquote>
<div><p>Now what?</p>
</div></blockquote>
<p>If you add this code and reload your game, once you’re logged in with a character in a room as its
location, you can play around:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="n">here</span><span class="o">.</span><span class="n">x</span>
<span class="nd">@py</span> <span class="n">here</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="mi">0</span>
<span class="nd">@py</span> <span class="n">here</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="mi">3</span>
<span class="nd">@py</span> <span class="n">here</span><span class="o">.</span><span class="n">z</span> <span class="o">=</span> <span class="o">-</span><span class="mi">2</span>
<span class="nd">@py</span> <span class="n">here</span><span class="o">.</span><span class="n">z</span> <span class="o">=</span> <span class="kc">None</span>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">py</span> <span class="n">here</span><span class="o">.</span><span class="n">x</span>
<span class="n">py</span> <span class="n">here</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">py</span> <span class="n">here</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="mi">3</span>
<span class="n">py</span> <span class="n">here</span><span class="o">.</span><span class="n">z</span> <span class="o">=</span> <span class="o">-</span><span class="mi">2</span>
<span class="n">py</span> <span class="n">here</span><span class="o">.</span><span class="n">z</span> <span class="o">=</span> <span class="kc">None</span>
</pre></div>
</div>
<p>The code might not be that easy to read, but you have to admit it’s fairly easy to use.</p>
</section>
<section id="some-additional-searches">
<h2>Some additional searches<a class="headerlink" href="#some-additional-searches" title="Permalink to this headline"></a></h2>
@ -305,23 +285,18 @@ Z=0?</p>
<span class="k">return</span> <span class="kc">None</span>
</pre></div>
</div>
<p>This solution includes a bit of <a class="reference external" href="https://docs.djangoproject.com/en/1.11/topics/db/queries/">Django
queries</a>.
Basically, what we do is reach for the object manager and search for objects with the matching tags.
Again, don’t spend too much time worrying about the mechanism, the method is quite easy to use:</p>
<p>This solution includes some <span class="xref myst">Django queries</span>. Basically, what we do is reach for the object manager and search for objects with the matching tags. Again, don’t spend too much time worrying about the mechanism, the method is quite easy to use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Room</span><span class="o">.</span><span class="n">get_room_at</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="o">-</span><span class="mi">3</span><span class="p">)</span>
</pre></div>
</div>
<p>Notice that this is a class method: you will call it from <code class="docutils literal notranslate"><span class="pre">Room</span></code> (the class), not an instance.
Though you still can:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@py here.get_room_at(3, 8, 0)
<p>Notice that this is a class method: you will call it from <code class="docutils literal notranslate"><span class="pre">Room</span></code> (the class), not an instance. Though you still can:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>py here.get_room_at(3, 8, 0)
</pre></div>
</div>
</section>
<section id="finding-several-rooms">
<h3>Finding several rooms<a class="headerlink" href="#finding-several-rooms" title="Permalink to this headline"></a></h3>
<p>Here’s another useful method that allows us to look for rooms around a given coordinate. This is
more advanced search and doing some calculation, beware! Look at the following section if you’re
<p>Here’s another useful method that allows us to look for rooms around a given coordinate. This is more advanced search and doing some calculation, beware! Look at the following section if you’re
lost.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">math</span> <span class="kn">import</span> <span class="n">sqrt</span>
@ -385,9 +360,7 @@ lost.</p>
<ol class="simple">
<li><p>We have specified coordinates as parameters. We determine a broad range using the distance.
That is, for each coordinate, we create a list of possible matches. See the example below.</p></li>
<li><p>We then search for the rooms within this broader range. It gives us a square
around our location. Some rooms are definitely outside the range. Again, see the example below
to follow the logic.</p></li>
<li><p>We then search for the rooms within this broader range. It gives us a square around our location. Some rooms are definitely outside the range. Again, see the example below to follow the logic.</p></li>
<li><p>We filter down the list and sort it by distance from the specified coordinates.</p></li>
</ol>
<p>Notice that we only search starting at step 2. Thus, the Django search doesn’t look and cache all
@ -406,24 +379,16 @@ optimized to be quick and efficient.</p>
<span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span>
</pre></div>
</div>
<p>The X coordinates are given below. The Y coordinates are given on the left. This is a simple
square with 16 rooms: 4 on each line, 4 lines of them. All the rooms are identified by letters in
this example: the first line at the top has rooms A to D, the second E to H, the third I to L and
the fourth M to P. The bottom-left room, X=1 and Y=1, is M. The upper-right room X=4 and Y=4 is D.</p>
<p>So let’s say we want to find all the neighbors, distance 1, from the room J. J is at X=2, Y=2.</p>
<p>The X coordinates are given below. The Y coordinates are given on the left. This is a simple square with 16 rooms: 4 on each line, 4 lines of them. All the rooms are identified by letters in this example: the first line at the top has rooms A to D, the second E to H, the third I to L and the fourth M to P. The bottom-left room, X=1 and Y=1, is M. The upper-right room X=4 and Y=4 is D.
So let’s say we want to find all the neighbors, distance 1, from the room J. J is at X=2, Y=2.</p>
<p>So we use:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Room.get_rooms_around(x=2, y=2, z=0, distance=1)
# we&#39;ll assume a z coordinate of 0 for simplicity
</pre></div>
</div>
<ol class="simple">
<li><p>First, this method gets all the rooms in a square around J. So it gets E F G, I J K, M N O. If
you want, draw the square around these coordinates to see what’s happening.</p></li>
<li><p>Next, we browse over this list and check the real distance between J (X=2, Y=2) and the room.
The four corners of the square are not in this circle. For instance, the distance between J and M
is not 1. If you draw a circle of center J and radius 1, you’ll notice that the four corners of our
square (E, G, M and O) are not in this circle. So we remove them.</p></li>
<li><p>We sort by distance from J.</p></li>
<li><p>First, this method gets all the rooms in a square around J. So it gets E F G, I J K, M N O. If you want, draw the square around these coordinates to see what’s happening.</p></li>
<li><p>Next, we browse over this list and check the real distance between J (X=2, Y=2) and the room. The four corners of the square are not in this circle. For instance, the distance between J and M is not 1. If you draw a circle of center J and radius 1, you’ll notice that the four corners of our square (E, G, M and O) are not in this circle. So we remove them. 3. We sort by distance from J.</p></li>
</ol>
<p>So in the end we might obtain something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
@ -437,11 +402,11 @@ square (E, G, M and O) are not in this circle. So we remove them.</p></li>
</div>
<p>You can try with more examples if you want to see this in action.</p>
</section>
<section id="to-conclude">
<h3>To conclude<a class="headerlink" href="#to-conclude" title="Permalink to this headline"></a></h3>
<p>You can definitely use this system to map other objects, not just rooms. You can easily remove the
`Z coordinate too, if you simply need X and Y.</p>
</section>
<section id="to-conclude">
<h2>To conclude<a class="headerlink" href="#to-conclude" title="Permalink to this headline"></a></h2>
<p>You can also use this system to map other objects, not just rooms. You can easily remove the
<code class="docutils literal notranslate"><span class="pre">Z</span></code> coordinate too, if you simply need <code class="docutils literal notranslate"><span class="pre">X</span></code> and <code class="docutils literal notranslate"><span class="pre">Y</span></code>.</p>
</section>
</section>
@ -461,14 +426,14 @@ square (E, G, M and O) are not in this circle. So we remove them.</p></li>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Dynamic-In-Game-Map.html" title="Dynamic In Game Map"
<a href="Tutorial-Displaying-Room-Map.html" title="Show a dynamic map of rooms"
>next</a> |</li>
<li class="right" >
<a href="Weather-Tutorial.html" title="Weather Tutorial"
<a href="Tutorial-Weather-Effects.html" title="Adding Weather messages to a Room"
>previous</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-1"><a href="Howtos-Overview.html" >Tutorials and Howto’s</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Coordinates</a></li>
<li class="nav-item nav-item-this"><a href="">Adding room coordinates to your game</a></li>
</ul>
<div class="develop">develop branch</div>
</div>