<h1>Evennia Server Lifecycle<aclass="headerlink"href="#evennia-server-lifecycle"title="Permalink to this headline">¶</a></h1>
<p>As part of your game design you may want to change how Evennia behaves when starting or stopping. A common use case would be to start up some piece of custom code you want to always have available once the server is up.</p>
<p>Evennia has three main life cycles, all of which you can add custom behavior for:</p>
<li><p><strong>Database life cycle</strong>: Evennia uses a database. This exists in parallel to the code changes you do. The database exists until you choose to reset or delete it. Doing so doesn’t require re-downloading Evennia.</p></li>
<li><p><strong>Reboot life cycle</strong>: From When Evennia starts to it being fully shut down, which means both Portal and Server are stopped. At the end of this cycle, all players are disconnected.</p></li>
<li><p><strong>Reload life cycle:</strong> This is the main runtime, until a “reload” event. Reloads refreshes game code but do not kick any players.</p></li>
<h2>When Evennia starts for the first time<aclass="headerlink"href="#when-evennia-starts-for-the-first-time"title="Permalink to this headline">¶</a></h2>
<p>This is the beginning of the <strong>Database life cycle</strong>, just after the database is created and migrated for the first time (or after it was deleted and re-built). See <aclass="reference internal"href="../Setup/Choosing-a-Database.html"><spanclass="doc std std-doc">Choosing a Database</span></a> for instructions on how to reset a database, should you want to re-run this sequence after the first time.</p>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">evennia.server.initial_setup.handle_setup(last_step=None)</span></code>: Evennia’s core initialization function. This is what creates the #1 Character (tied to the superuser account) and <codeclass="docutils literal notranslate"><spanclass="pre">Limbo</span></code> room. It calls the next hook below and also understands to restart at the last failed step if there was some issue. You should normally not override this function unless you <em>really</em> know what you are doing. To override, change <codeclass="docutils literal notranslate"><spanclass="pre">settings.INITIAL_SETUP_MODULE</span></code> to your own module with a <codeclass="docutils literal notranslate"><spanclass="pre">handle_setup</span></code> function in it.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/conf/at_initial_setup.py</span></code> contains a single function, <codeclass="docutils literal notranslate"><spanclass="pre">at_initial_setup()</span></code>, which will be called without arguments. It’s called last in the setup sequence by the above function. Use this to add your own custom behavior or to tweak the initialization. If you for example wanted to change the auto-generated Limbo room, you should do it from here. If you want to change where this function is found, you can do so by changing <codeclass="docutils literal notranslate"><spanclass="pre">settings.AT_INITIAL_SETUP_HOOK_MODULE</span></code>.</p></li>
</ol>
</section>
<sectionid="when-evennia-starts-and-shutdowns">
<h2>When Evennia starts and shutdowns<aclass="headerlink"href="#when-evennia-starts-and-shutdowns"title="Permalink to this headline">¶</a></h2>
<p>This is part of the <strong>Reboot life cycle</strong>. Evennia consists of two main processes, the <aclass="reference internal"href="../Components/Portal-And-Server.html"><spanclass="doc std std-doc">Portal and the Server</span></a>. On a reboot or shutdown, both Portal and Server shuts down, which means all players are disconnected.</p>
<p>Each process call a series of hooks located in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/conf/at_server_startstop.py</span></code>. You can customize the module used with <codeclass="docutils literal notranslate"><spanclass="pre">settings.AT_SERVER_STARTSTOP_MODULE</span></code> - this can even be a list of modules, if so, the appropriately-named functions will be called from each module, in sequence.</p>
<p>All hooks are called without arguments.</p>
<blockquote>
<div><p>The use of the term ‘server’ in the hook-names indicate the whole of Evennia, not just the <codeclass="docutils literal notranslate"><spanclass="pre">Server</span></code> component.</p>
</div></blockquote>
<sectionid="server-cold-start">
<h3>Server cold start<aclass="headerlink"href="#server-cold-start"title="Permalink to this headline">¶</a></h3>
<p>Starting the server from zero, after a full stop. This is done with <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">start</span></code> from the terminal.</p>
<olclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_init()</span></code> - Always called first in the startup sequence.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_cold_start()</span></code> - Only called on cold starts.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_start()</span></code> - Always called last in the startup sequece.</p></li>
</ol>
</section>
<sectionid="server-cold-shutdown">
<h3>Server cold shutdown<aclass="headerlink"href="#server-cold-shutdown"title="Permalink to this headline">¶</a></h3>
<p>Shutting everything down. Done with <codeclass="docutils literal notranslate"><spanclass="pre">shutdown</span></code> in-game or <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">stop</span></code> from the terminal.</p>
<olclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_cold_stop()</span></code> - Only called on cold stops.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_stop()</span></code> - Always called last in the stopping sequence.</p></li>
</ol>
</section>
<sectionid="server-reboots">
<h3>Server reboots<aclass="headerlink"href="#server-reboots"title="Permalink to this headline">¶</a></h3>
<p>This is done with <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">reboot</span></code> and effectively constitutes an automatic cold shutdown followed by a cold start controlled from the <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> launcher. There are no special <codeclass="docutils literal notranslate"><spanclass="pre">reboot</span></code> hooks for this, instead it looks like you’d expect:</p>
<h2>When Evennia reloads and resets<aclass="headerlink"href="#when-evennia-reloads-and-resets"title="Permalink to this headline">¶</a></h2>
<p>This is the <strong>Reload life cycle</strong>. As mentioned above, Evennia consists of two components, the <aclass="reference internal"href="../Components/Portal-And-Server.html"><spanclass="doc std std-doc">Portal and Server</span></a>. During a reload, only the <codeclass="docutils literal notranslate"><spanclass="pre">Server</span></code> component is shut down and restarted. Since the Portal stays up, players are not disconnected.</p>
<p>All hooks are called without arguments.</p>
<sectionid="server-reload">
<h3>Server reload<aclass="headerlink"href="#server-reload"title="Permalink to this headline">¶</a></h3>
<p>Reloads are initiated with the <codeclass="docutils literal notranslate"><spanclass="pre">reload</span></code> command in-game, or with <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">reload</span></code> from the terminal.</p>
<olclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_reload_stop()</span></code> - Only called on reload stops.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_stop</span></code> - Always called last in the stopping sequence.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_init()</span></code> - Always called first in startup sequence.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_reload_start()</span></code> - Only called on a reload (re)start.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_server_start()</span></code> - Always called last in the startup sequence.</p></li>
</ol>
</section>
<sectionid="server-reset">
<h3>Server reset<aclass="headerlink"href="#server-reset"title="Permalink to this headline">¶</a></h3>
<p>A ‘reset’ is a hybrid reload state, where the reload is treated as a cold shutdown only for the sake of running hooks (players are not disconnected). It’s run with <codeclass="docutils literal notranslate"><spanclass="pre">reset</span></code> in-game or with <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">reset</span></code> from the terminal.</p>
