<h1>Creating rooms from an ascii map<aclass="headerlink"href="#creating-rooms-from-an-ascii-map"title="Permalink to this headline">¶</a></h1>
<p>This tutorial describes the creation of an in-game map display based on a pre-drawn map. It goes with the <aclass="reference internal"href="Contrib-Mapbuilder.html"><spanclass="doc std std-doc">Mapbuilder contrib</span></a>. It also details how to use the <aclass="reference internal"href="../Components/Batch-Code-Processor.html"><spanclass="doc std std-doc">Batch code processor</span></a> for advanced building.</p>
≈↑│↑∩ The merger of two roads. To the north looms a mighty castle.
O─O─O To the south, the glow of a campfire can be seen. To the east lie
≈↑│↑∩ the vast mountains and to the west is heard the waves of the sea.
↑▲O▲↑
Exits: north(#8), east(#9), south(#10), west(#11)
</pre></div>
</div>
</li>
</ol>
<p>We will henceforth assume your game folder is name named <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code> and that you haven’t modified the
dkefault commands. We will also not be using <aclass="reference internal"href="../Concepts/Colors.html"><spanclass="doc std std-doc">Colors</span></a> for our map since they
≈≈↑╔═╗↑∩∩ Places the account can visit are indicated by "O".
≈≈↑║O║↑∩∩ Up the top is a castle visitable by the account.
≈≈↑╚∞╝↑∩∩ To the right is a cottage and to the left the beach.
≈≈≈↑│↑∩∩∩ And down the bottom is a camp site with tents.
≈≈O─O─O⌂∩ In the center is the starting location, a crossroads
≈≈≈↑│↑∩∩∩ which connect the four other areas.
≈≈↑▲O▲↑∩∩
≈≈↑↑▲↑↑∩∩
≈≈↑↑↑↑↑∩∩
</pre></div>
</div>
<p>There are many considerations when making a game map depending on the play style and requirements
you intend to implement. Here we will display a 5x5 character map of the area surrounding the
account. This means making sure to account for 2 characters around every visitable location. Good
planning at this stage can solve many problems before they happen.</p>
</section>
<sectionid="creating-a-map-object">
<h2>Creating a Map Object<aclass="headerlink"href="#creating-a-map-object"title="Permalink to this headline">¶</a></h2>
<p>In this section we will try to create an actual “map” object that an account can pick up and look
at.</p>
<p>Evennia offers a range of <aclass="reference internal"href="../Components/Default-Commands.html"><spanclass="doc std std-doc">default commands</span></a> for
<aclass="reference internal"href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Building-Quickstart.html"><spanclass="doc std std-doc">creating objects and rooms in-game</span></a>. While readily accessible, these commands are made to do very
specific, restricted things and will thus not offer as much flexibility to experiment (for an
advanced exception see <aclass="reference internal"href="../Components/FuncParser.html"><spanclass="doc std std-doc">the FuncParser</span></a>). Additionally, entering long
descriptions and properties over and over in the game client can become tedious; especially when
testing and you may want to delete and recreate things over and over.</p>
<p>To overcome this, Evennia offers <aclass="reference internal"href="../Components/Batch-Processors.html"><spanclass="doc std std-doc">batch processors</span></a> that work as input-files
created out-of-game. In this tutorial we’ll be using the more powerful of the two available batch
processors, the <aclass="reference internal"href="../Components/Batch-Code-Processor.html"><spanclass="doc std std-doc">Batch Code Processor </span></a>, called with the <codeclass="docutils literal notranslate"><spanclass="pre">@batchcode</span></code> command.
This is a very powerful tool. It allows you to craft Python files to act as blueprints of your
entire game world. These files have access to use Evennia’s Python API directly. Batchcode allows
for easy editing and creation in whatever text editor you prefer, avoiding having to manually build
the world line-by-line inside the game.</p>
<blockquote>
<div><p>Important warning: <codeclass="docutils literal notranslate"><spanclass="pre">@batchcode</span></code>’s power is only rivaled by the <codeclass="docutils literal notranslate"><spanclass="pre">@py</span></code> command. Batchcode is so
before you let others (such as <codeclass="docutils literal notranslate"><spanclass="pre">Developer</span></code>- level staff) run <codeclass="docutils literal notranslate"><spanclass="pre">@batchcode</span></code> on their own - make sure
you are okay with them running <em>arbitrary Python code</em> on your server.</p>
</div></blockquote>
<p>While a simple example, the map object it serves as good way to try out <codeclass="docutils literal notranslate"><spanclass="pre">@batchcode</span></code>. Go to
<codeclass="docutils literal notranslate"><spanclass="pre">mygame/world</span></code> and create a new file there named <codeclass="docutils literal notranslate"><spanclass="pre">batchcode_map.py</span></code>:</p>
<spanclass="c1"># This message lets us know our map was created successfully.</span>
<spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"A map appears out of thin air and falls to the ground."</span><spanclass="p">)</span>
</pre></div>
</div>
<p>Log into your game project as the superuser and run the command</p>
<p>This will load your <codeclass="docutils literal notranslate"><spanclass="pre">batchcode_map.py</span></code> file and execute the code (Evennia will look in your <codeclass="docutils literal notranslate"><spanclass="pre">world/</span></code>
folder automatically so you don’t need to specify it).</p>
<p>A new map object should have appeared on the ground. You can view the map by using <codeclass="docutils literal notranslate"><spanclass="pre">look</span><spanclass="pre">map</span></code>. Let’s
take it with the <codeclass="docutils literal notranslate"><spanclass="pre">get</span><spanclass="pre">map</span></code> command. We’ll need it in case we get lost!</p>
</section>
<sectionid="building-the-map-areas">
<h2>Building the map areas<aclass="headerlink"href="#building-the-map-areas"title="Permalink to this headline">¶</a></h2>
<p>We’ve just used batchcode to create an object useful for our adventures. But the locations on that
map does not actually exist yet - we’re all mapped up with nowhere to go! Let’s use batchcode to
build a game area based on our map. We have five areas outlined: a castle, a cottage, a campsite, a
coastal beach and the crossroads which connects them. Create a new batchcode file for this in
<codeclass="docutils literal notranslate"><spanclass="pre">mygame/world</span></code>, named <codeclass="docutils literal notranslate"><spanclass="pre">batchcode_world.py</span></code>.</p>
<spanclass="c1"># This is where we set up the southern camp.</span>
<spanclass="n">south</span><spanclass="o">.</span><spanclass="n">db</span><spanclass="o">.</span><spanclass="n">desc</span><spanclass="o">=</span><spanclass="s2">"Surrounding a clearing are a number of "</span> \
<spanclass="s2">"tribal tents and at their centre a roaring fire."</span>
<spanclass="c1"># This is where we set up the western coast.</span>
<spanclass="n">west</span><spanclass="o">.</span><spanclass="n">db</span><spanclass="o">.</span><spanclass="n">desc</span><spanclass="o">=</span><spanclass="s2">"The dark forest halts to a sandy beach. "</span> \
<spanclass="s2">"The sound of crashing waves calms the soul."</span>
<p>Apply this new batch code with <codeclass="docutils literal notranslate"><spanclass="pre">@batchcode</span><spanclass="pre">batchcode_world</span></code>. If there are no errors in the code we
now have a nice mini-world to explore. Remember that if you get lost you can look at the map we
created!</p>
</section>
<sectionid="in-game-minimap">
<h2>In-game minimap<aclass="headerlink"href="#in-game-minimap"title="Permalink to this headline">¶</a></h2>
<p>Now we have a landscape and matching map, but what we really want is a mini-map that displays
whenever we move to a room or use the <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code> command.</p>
<p>We <em>could</em> manually enter a part of the map into the description of every room like we did our map
object description. But some MUDs have tens of thousands of rooms! Besides, if we ever changed our
map we would have to potentially alter a lot of those room descriptions manually to match the
change. So instead we will make one central module to hold our map. Rooms will reference this
central location on creation and the map changes will thus come into effect when next running our
batchcode.</p>
<p>To make our mini-map we need to be able to cut our full map into parts. To do this we need to put it
in a format which allows us to do that easily. Luckily, python allows us to treat strings as lists
of characters allowing us to pick out the characters we need.</p>
<p>With our map_module set up, let’s replace our hardcoded map in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/world/batchcode_map.py</span></code> with
a reference to our map module. Make sure to import our map_module!</p>
<spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"A map appears out of thin air and falls to the ground."</span><spanclass="p">)</span>
</pre></div>
</div>
<p>Log into Evennia as the superuser and run this batchcode. If everything worked our new map should
look exactly the same as the old map - you can use <codeclass="docutils literal notranslate"><spanclass="pre">@delete</span></code> to delete the old one (use a number to
pick which to delete).</p>
<p>Now, lets turn our attention towards our game’s rooms. Let’s use the <codeclass="docutils literal notranslate"><spanclass="pre">return_minimap</span></code> method we
created above in order to include a minimap in our room descriptions. This is a little more
complicated.</p>
<p>By itself we would have to settle for either the map being <em>above</em> the description with
<codeclass="docutils literal notranslate"><spanclass="pre">room.db.desc</span><spanclass="pre">=</span><spanclass="pre">map_string</span><spanclass="pre">+</span><spanclass="pre">description_string</span></code>, or the map going <em>below</em> by reversing their order.
Both options are rather unsatisfactory - we would like to have the map next to the text! For this
solution we’ll explore the utilities that ship with Evennia. Tucked away in <codeclass="docutils literal notranslate"><spanclass="pre">evennia\evennia\utils</span></code>
is a little module called <aclass="reference external"href="https://github.com/evennia/evennia/blob/main/evennia.utils.evtable">EvTable</a> . This is an advanced ASCII table
<p>Before we run our new batchcode, if you are anything like me you would have something like 100 maps
lying around and 3-4 different versions of our rooms extending from limbo. Let’s wipe it all and
start with a clean slate. In Command Prompt you can run <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">flush</span></code> to clear the database and
start anew. It won’t reset dbref values however, so if you are at #100 it will start from there.
Alternatively you can navigate to <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server</span></code> and delete the <codeclass="docutils literal notranslate"><spanclass="pre">evennia.db3</span></code> file. Now in Command
Prompt use <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">migrate</span></code> to have a completely freshly made database.</p>
<p>Log in to evennia and run <codeclass="docutils literal notranslate"><spanclass="pre">@batchcode</span><spanclass="pre">batchcode_world</span></code> and you’ll have a little world to explore.</p>
</section>
<sectionid="conclusions">
<h2>Conclusions<aclass="headerlink"href="#conclusions"title="Permalink to this headline">¶</a></h2>
<p>You should now have a mapped little world and a basic understanding of batchcode, EvTable and how
easily new game defining features can be added to Evennia.</p>
<p>You can easily build from this tutorial by expanding the map and creating more rooms to explore. Why
not add more features to your game by trying other tutorials: [Add weather to your world](Weather-
Tutorial), <aclass="reference internal"href="../Howtos/Tutorial-NPC-Reacting.html"><spanclass="doc std std-doc">fill your world with NPC’s</span></a> or
<aclass="reference internal"href="../Howtos/Turn-based-Combat-System.html"><spanclass="doc std std-doc">implement a combat system</span></a>.</p>
