evennia/docs/0.x/Building-Quickstart.html
2023-12-20 19:10:09 +01:00

383 lines
No EOL
27 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" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Building Quickstart &#8212; Evennia 0.9.5 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>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</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 0.9.5</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Building Quickstart</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="building-quickstart">
<h1>Building Quickstart<a class="headerlink" href="#building-quickstart" title="Permalink to this headline"></a></h1>
<p>The <a class="reference internal" href="Default-Commands.html"><span class="doc std std-doc">default command</span></a> definitions coming with Evennia
follows a style <a class="reference internal" href="Using-MUX-as-a-Standard.html"><span class="doc std std-doc">similar</span></a> to that of MUX, so the
commands should be familiar if you used any such code bases before.</p>
<blockquote>
<div><p>Throughout the larger documentation you may come across commands prefixed
with <code class="docutils literal notranslate"><span class="pre">&#64;</span></code>. This is just an optional marker used in some places to make a
command stand out. Evennia defaults to ignoring the use of <code class="docutils literal notranslate"><span class="pre">&#64;</span></code> in front of
your command (so entering <code class="docutils literal notranslate"><span class="pre">dig</span></code> is the same as entering <code class="docutils literal notranslate"><span class="pre">&#64;dig</span></code>).</p>
</div></blockquote>
<p>The default commands have the following style (where <code class="docutils literal notranslate"><span class="pre">[...]</span></code> marks optional parts):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> command[/switch/switch...] [arguments ...]
</pre></div>
</div>
<p>A <em>switch</em> is a special, optional flag to the command to make it behave differently. It is always
put directly after the command name, and begins with a forward slash (<code class="docutils literal notranslate"><span class="pre">/</span></code>). The <em>arguments</em> are one
or more inputs to the commands. Its common to use an equal sign (<code class="docutils literal notranslate"><span class="pre">=</span></code>) when assigning something to
an object.</p>
<p>Below are some examples of commands you can try when logged in to the game. Use <code class="docutils literal notranslate"><span class="pre">help</span> <span class="pre">&lt;command&gt;</span></code> for
learning more about each command and their detailed options.</p>
<section id="stepping-down-from-godhood">
<h2>Stepping Down From Godhood<a class="headerlink" href="#stepping-down-from-godhood" title="Permalink to this headline"></a></h2>
<p>If you just installed Evennia, your very first player account is called user #1, also known as the
<em>superuser</em> or <em>god user</em>. This user is very powerful, so powerful that it will override many game
restrictions such as locks. This can be useful, but it also hides some functionality that you might
want to test.</p>
<p>To temporarily step down from your superuser position you can use the <code class="docutils literal notranslate"><span class="pre">quell</span></code> command in-game:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>quell
</pre></div>
</div>
<p>This will make you start using the permission of your current characters level instead of your
superuser level. If you didnt change any settings your game Character should have an <em>Developer</em>
level permission - high as can be without bypassing locks like the superuser does. This will work
fine for the examples on this page. Use <code class="docutils literal notranslate"><span class="pre">unquell</span></code> to get back to superuser status again afterwards.</p>
</section>
<section id="creating-an-object">
<h2>Creating an Object<a class="headerlink" href="#creating-an-object" title="Permalink to this headline"></a></h2>
<p>Basic objects can be anything swords, flowers and non-player characters. They are created using
the <code class="docutils literal notranslate"><span class="pre">create</span></code> command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>create box
</pre></div>
</div>
<p>This created a new box (of the default object type) in your inventory. Use the command <code class="docutils literal notranslate"><span class="pre">inventory</span></code>
(or <code class="docutils literal notranslate"><span class="pre">i</span></code>) to see it. Now, box is a rather short name, lets rename it and tack on a few aliases.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>name box = very large box;box;very;crate
</pre></div>
</div>
<p>We now renamed the box to <em>very large box</em> (and this is what we will see when looking at it), but we
will also recognize it by any of the other names we give - like <em>crate</em> or simply <em>box</em> as before.
We could have given these aliases directly after the name in the <code class="docutils literal notranslate"><span class="pre">create</span></code> command, this is true for
all creation commands - you can always tag on a list of <code class="docutils literal notranslate"><span class="pre">;</span></code>-separated aliases to the name of your
new object. If you had wanted to not change the name itself, but to only add aliases, you could have
used the <code class="docutils literal notranslate"><span class="pre">alias</span></code> command.</p>
<p>We are currently carrying the box. Lets drop it (there is also a short cut to create and drop in
one go by using the <code class="docutils literal notranslate"><span class="pre">/drop</span></code> switch, for example <code class="docutils literal notranslate"><span class="pre">create/drop</span> <span class="pre">box</span></code>).</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>drop box
</pre></div>
</div>
<p>Hey presto - there it is on the ground, in all its normality.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>examine box
</pre></div>
</div>
<p>This will show some technical details about the box object. For now we will ignore what this
information means.</p>
<p>Try to <code class="docutils literal notranslate"><span class="pre">look</span></code> at the box to see the (default) description.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>look box
You see nothing special.
</pre></div>
</div>
<p>The description you get is not very exciting. Lets add some flavor.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>describe box = This is a large and very heavy box.
</pre></div>
</div>
<p>If you try the <code class="docutils literal notranslate"><span class="pre">get</span></code> command we will pick up the box. So far so good, but if we really want this to
be a large and heavy box, people should <em>not</em> be able to run off with it that easily. To prevent
this we need to lock it down. This is done by assigning a <em>Lock</em> to it. Make sure the box was
dropped in the room, then try this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>lock box = get:false()
</pre></div>
</div>
<p>Locks represent a rather <a class="reference internal" href="Locks.html"><span class="doc std std-doc">big topic</span></a>, but for now that will do what we want. This will lock
the box so noone can lift it. The exception is superusers, they override all locks and will pick it
up anyway. Make sure you are quelling your superuser powers and try to get the box now:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; get box
You can&#39;t get that.
</pre></div>
</div>
<p>Think thís default error message looks dull? The <code class="docutils literal notranslate"><span class="pre">get</span></code> command looks for an <a class="reference internal" href="Attributes.html"><span class="doc std std-doc">Attribute</span></a>
named <code class="docutils literal notranslate"><span class="pre">get_err_msg</span></code> for returning a nicer error message (we just happen to know this, you would need
to peek into the
<a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/commands/default/general.py#L235">code</a> for
the <code class="docutils literal notranslate"><span class="pre">get</span></code> command to find out.). You set attributes using the <code class="docutils literal notranslate"><span class="pre">set</span></code> command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>set box/get_err_msg = It&#39;s way too heavy for you to lift.
</pre></div>
</div>
<p>Try to get it now and you should see a nicer error message echoed back to you. To see what this
message string is in the future, you can use examine.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>examine box/get_err_msg
</pre></div>
</div>
<p>Examine will return the value of attributes, including color codes. <code class="docutils literal notranslate"><span class="pre">examine</span> <span class="pre">here/desc</span></code> would return
the raw description of your current room (including color codes), so that you can copy-and-paste to
set its description to something else.</p>
<p>You create new Commands (or modify existing ones) in Python outside the game. See the <a class="reference internal" href="Adding-Command-Tutorial.html"><span class="doc std std-doc">Adding
Commands tutorial</span></a> for help with creating your first own Command.</p>
</section>
<section id="get-a-personality">
<h2>Get a Personality<a class="headerlink" href="#get-a-personality" title="Permalink to this headline"></a></h2>
<p><a class="reference internal" href="Scripts.html"><span class="doc std std-doc">Scripts</span></a> are powerful out-of-character objects useful for many “under the hood” things.
One of their optional abilities is to do things on a timer. To try out a first script, lets put one
on ourselves. There is an example script in <code class="docutils literal notranslate"><span class="pre">evennia/contrib/tutorial_examples/bodyfunctions.py</span></code>
that is called <code class="docutils literal notranslate"><span class="pre">BodyFunctions</span></code>. To add this to us we will use the <code class="docutils literal notranslate"><span class="pre">script</span></code> command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>script self = tutorial_examples.bodyfunctions.BodyFunctions
</pre></div>
</div>
<p>(note that you dont have to give the full path as long as you are pointing to a place inside the
<code class="docutils literal notranslate"><span class="pre">contrib</span></code> directory, its one of the places Evennia looks for Scripts). Wait a while and you will
notice yourself starting making random observations.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>script self
</pre></div>
</div>
<p>This will show details about scripts on yourself (also <code class="docutils literal notranslate"><span class="pre">examine</span></code> works). You will see how long it is
until it “fires” next. Dont be alarmed if nothing happens when the countdown reaches zero - this
particular script has a randomizer to determine if it will say something or not. So you will not see
output every time it fires.</p>
<p>When you are tired of your characters “insights”, kill the script with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>script/stop self = tutorial_examples.bodyfunctions.BodyFunctions
</pre></div>
</div>
<p>You create your own scripts in Python, outside the game; the path you give to <code class="docutils literal notranslate"><span class="pre">script</span></code> is literally
the Python path to your script file. The <a class="reference internal" href="Scripts.html"><span class="doc std std-doc">Scripts</span></a> page explains more details.</p>
</section>
<section id="pushing-your-buttons">
<h2>Pushing Your Buttons<a class="headerlink" href="#pushing-your-buttons" title="Permalink to this headline"></a></h2>
<p>If we get back to the box we made, there is only so much fun you can do with it at this point. Its
just a dumb generic object. If you renamed it to <code class="docutils literal notranslate"><span class="pre">stone</span></code> and changed its description noone would be
the wiser. However, with the combined use of custom <a class="reference internal" href="Typeclasses.html"><span class="doc std std-doc">Typeclasses</span></a>, <a class="reference internal" href="Scripts.html"><span class="doc std std-doc">Scripts</span></a>
and object-based <a class="reference internal" href="Commands.html"><span class="doc std std-doc">Commands</span></a>, you could expand it and other items to be as unique, complex
and interactive as you want.</p>
<p>Lets take an example. So far we have only created objects that use the default object typeclass
named simply <code class="docutils literal notranslate"><span class="pre">Object</span></code>. Lets create an object that is a little more interesting. Under
<code class="docutils literal notranslate"><span class="pre">evennia/contrib/tutorial_examples</span></code> there is a module <code class="docutils literal notranslate"><span class="pre">red_button.py</span></code>. It contains the enigmatic
<code class="docutils literal notranslate"><span class="pre">RedButton</span></code> typeclass.</p>
<p>Lets make us one of <em>those</em>!</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>create/drop button:tutorial_examples.red_button.RedButton
</pre></div>
</div>
<p>We import the RedButton python class the same way you would import it in Python except Evennia makes
sure to look in<code class="docutils literal notranslate"><span class="pre">evennia/contrib/</span></code> so you dont have to write the full path every time. There you go</p>
<ul class="simple">
<li><p>one red button.</p></li>
</ul>
<p>The RedButton is an example object intended to show off a few of Evennias features. You will find
that the <a class="reference internal" href="Typeclasses.html"><span class="doc std std-doc">Typeclass</span></a> and <a class="reference internal" href="Commands.html"><span class="doc std std-doc">Commands</span></a> controlling it are inside
<code class="docutils literal notranslate"><span class="pre">evennia/contrib/tutorial_examples/</span></code>.</p>
<p>If you wait for a while (make sure you dropped it!) the button will blink invitingly. Why dont you
try to push it …? Surely a big red button is meant to be pushed. You know you want to.</p>
</section>
<section id="making-yourself-a-house">
<h2>Making Yourself a House<a class="headerlink" href="#making-yourself-a-house" title="Permalink to this headline"></a></h2>
<p>The main command for shaping the game world is <code class="docutils literal notranslate"><span class="pre">dig</span></code>. For example, if you are standing in Limbo you
can dig a route to your new house location like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>dig house = large red door;door;in,to the outside;out
</pre></div>
</div>
<p>This will create a new room named house. Spaces at the start/end of names and aliases are ignored
so you could put more air if you wanted. This call will directly create an exit from your current
location named large red door and a corresponding exit named to the outside in the house room
leading back to Limbo. We also define a few aliases to those exits, so people dont have to write
the full thing all the time.</p>
<p>If you wanted to use normal compass directions (north, west, southwest etc), you could do that with
<code class="docutils literal notranslate"><span class="pre">dig</span></code> too. But Evennia also has a limited version of <code class="docutils literal notranslate"><span class="pre">dig</span></code> that helps for compass directions (and
also up/down and in/out). Its called <code class="docutils literal notranslate"><span class="pre">tunnel</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>tunnel sw = cliff
</pre></div>
</div>
<p>This will create a new room “cliff” with an exit “southwest” leading there and a path “northeast”
leading back from the cliff to your current location.</p>
<p>You can create new exits from where you are using the <code class="docutils literal notranslate"><span class="pre">open</span></code> command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>open north;n = house
</pre></div>
</div>
<p>This opens an exit <code class="docutils literal notranslate"><span class="pre">north</span></code> (with an alias <code class="docutils literal notranslate"><span class="pre">n</span></code>) to the previously created room <code class="docutils literal notranslate"><span class="pre">house</span></code>.</p>
<p>If you have many rooms named <code class="docutils literal notranslate"><span class="pre">house</span></code> you will get a list of matches and have to select which one you
want to link to. You can also give its database (#dbref) number, which is unique to every object.
This can be found with the <code class="docutils literal notranslate"><span class="pre">examine</span></code> command or by looking at the latest constructions with
<code class="docutils literal notranslate"><span class="pre">objects</span></code>.</p>
<p>Follow the north exit to your house or <code class="docutils literal notranslate"><span class="pre">teleport</span></code> to it:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>north
</pre></div>
</div>
<p>or:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>teleport house
</pre></div>
</div>
<p>To manually open an exit back to Limbo (if you didnt do so with the <code class="docutils literal notranslate"><span class="pre">dig</span></code> command):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>open door = limbo
</pre></div>
</div>
<p>(or give limbos dbref which is #2)</p>
</section>
<section id="reshuffling-the-world">
<h2>Reshuffling the World<a class="headerlink" href="#reshuffling-the-world" title="Permalink to this headline"></a></h2>
<p>You can find things using the <code class="docutils literal notranslate"><span class="pre">find</span></code> command. Assuming you are back at <code class="docutils literal notranslate"><span class="pre">Limbo</span></code>, lets teleport the
<em>large box to our house</em>.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; teleport box = house
very large box is leaving Limbo, heading for house.
Teleported very large box -&gt; house.
</pre></div>
</div>
<p>We can still find the box by using find:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; find box
One Match(#1-#8):
very large box(#8) - src.objects.objects.Object
</pre></div>
</div>
<p>Knowing the <code class="docutils literal notranslate"><span class="pre">#dbref</span></code> of the box (#8 in this example), you can grab the box and get it back here
without actually yourself going to <code class="docutils literal notranslate"><span class="pre">house</span></code> first:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>teleport #8 = here
</pre></div>
</div>
<p>(You can usually use <code class="docutils literal notranslate"><span class="pre">here</span></code> to refer to your current location. To refer to yourself you can use
<code class="docutils literal notranslate"><span class="pre">self</span></code> or <code class="docutils literal notranslate"><span class="pre">me</span></code>). The box should now be back in Limbo with you.</p>
<p>We are getting tired of the box. Lets destroy it.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>destroy box
</pre></div>
</div>
<p>You can destroy many objects in one go by giving a comma-separated list of objects (or their
#dbrefs, if they are not in the same location) to the command.</p>
</section>
<section id="adding-a-help-entry">
<h2>Adding a Help Entry<a class="headerlink" href="#adding-a-help-entry" title="Permalink to this headline"></a></h2>
<p>An important part of building is keeping the help files updated. You can add, delete and append to
existing help entries using the <code class="docutils literal notranslate"><span class="pre">sethelp</span></code> command.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sethelp/add MyTopic = This help topic is about ...
</pre></div>
</div>
</section>
<section id="adding-a-world">
<h2>Adding a World<a class="headerlink" href="#adding-a-world" title="Permalink to this headline"></a></h2>
<p>After this brief introduction to building you may be ready to see a more fleshed-out example.
Evennia comes with a tutorial world for you to explore.</p>
<p>First you need to switch back to <em>superuser</em> by using the <code class="docutils literal notranslate"><span class="pre">unquell</span></code> command. Next, place yourself in
<code class="docutils literal notranslate"><span class="pre">Limbo</span></code> and run the following command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>batchcommand tutorial_world.build
</pre></div>
</div>
<p>This will take a while (be patient and dont re-run the command). You will see all the commands used
to build the world scroll by as the world is built for you.</p>
<p>You will end up with a new exit from Limbo named <em>tutorial</em>. Apart from being a little solo-
adventure in its own right, the tutorial world is a good source for learning Evennia building (and
coding).</p>
<p>Read <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/contrib/tutorial_world/build.ev">the batch
file</a> to see
exactly how its built, step by step. See also more info about the tutorial world [here](Tutorial-
World-Introduction).</p>
</section>
</section>
<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="#">Building Quickstart</a><ul>
<li><a class="reference internal" href="#stepping-down-from-godhood">Stepping Down From Godhood</a></li>
<li><a class="reference internal" href="#creating-an-object">Creating an Object</a></li>
<li><a class="reference internal" href="#get-a-personality">Get a Personality</a></li>
<li><a class="reference internal" href="#pushing-your-buttons">Pushing Your Buttons</a></li>
<li><a class="reference internal" href="#making-yourself-a-house">Making Yourself a House</a></li>
<li><a class="reference internal" href="#reshuffling-the-world">Reshuffling the World</a></li>
<li><a class="reference internal" href="#adding-a-help-entry">Adding a Help Entry</a></li>
<li><a class="reference internal" href="#adding-a-world">Adding a World</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/Building-Quickstart.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li><a href="http://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb">IRC</a> -
<a href="https://discord.gg/NecFePw">Discord</a> -
<a href="https://groups.google.com/forum/#%21forum/evennia">Forums</a>
</li>
<li><a href="http://evennia.blogspot.com/">Evennia Dev blog</a> </li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="../1.0-dev/index.html">1.0-dev (develop branch)</a></li>
<li><a href="Building-Quickstart.html">0.9.5 (v0.9.5 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 0.9.5</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Building Quickstart</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>