<p>An Evennia <em>Session</em> represents one single established connection to the server. Depending on the
Evennia session, it is possible for a person to connect multiple times, for example using different
clients in multiple windows. Each such connection is represented by a session object.</p>
<p>A session object has its own <aclass="reference internal"href="Command-Sets.html"><spanclass="doc">cmdset</span></a>, usually the “unloggedin” cmdset. This is what
is used to show the login screen and to handle commands to create a new account (or
<aclass="reference internal"href="Accounts.html"><spanclass="doc">Account</span></a> in evennia lingo) read initial help and to log into the game with an existing
account. A session object can either be “logged in” or not. Logged in means that the user has
authenticated. When this happens the session is associated with an Account object (which is what
holds account-centric stuff). The account can then in turn puppet any number of objects/characters.</p>
<div><p>Warning: A Session is not <em>persistent</em> - it is not a <aclass="reference internal"href="Typeclasses.html"><spanclass="doc">Typeclass</span></a> and has no
connection to the database. The Session will go away when a user disconnects and you will lose any
custom data on it if the server reloads. The <codeclass="docutils literal notranslate"><spanclass="pre">.db</span></code> handler on Sessions is there to present a uniform
API (so you can assume <codeclass="docutils literal notranslate"><spanclass="pre">.db</span></code> exists even if you don’t know if you receive an Object or a Session),
but this is just an alias to <codeclass="docutils literal notranslate"><spanclass="pre">.ndb</span></code>. So don’t store any data on Sessions that you can’t afford to
<h2>Properties on Sessions<aclass="headerlink"href="#properties-on-sessions"title="Permalink to this headline">¶</a></h2>
<p>Here are some important properties available on (Server-)Sessions</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">sessid</span></code> - The unique session-id. This is an integer starting from 1.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">address</span></code> - The connected client’s address. Different protocols give different information here.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">logged_in</span></code> - <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> if the user authenticated to this session.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">account</span></code> - The <aclass="reference internal"href="Accounts.html"><spanclass="doc">Account</span></a> this Session is attached to. If not logged in yet, this is
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">puppet</span></code> - The <aclass="reference internal"href="Objects.html"><spanclass="doc">Character/Object</span></a> currently puppeted by this Account/Session combo. If
not logged in or in OOC mode, this is <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">ndb</span></code> - The <aclass="reference internal"href="Attributes.html"><spanclass="doc">Non-persistent Attribute</span></a> handler.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">db</span></code> - As noted above, Sessions don’t have regular Attributes. This is an alias to <codeclass="docutils literal notranslate"><spanclass="pre">ndb</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">cmdset</span></code> - The Session’s <aclass="reference internal"href="Command-Sets.html"><spanclass="doc">CmdSetHandler</span></a></p></li>
</ul>
<p>Session statistics are mainly used internally by Evennia.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">conn_time</span></code> - How long this Session has been connected</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">cmd_last</span></code> - Last active time stamp. This will be reset by sending <codeclass="docutils literal notranslate"><spanclass="pre">idle</span></code> keepalives.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">cmd_last_visible</span></code> - last active time stamp. This ignores <codeclass="docutils literal notranslate"><spanclass="pre">idle</span></code> keepalives and representes the
last time this session was truly visibly active.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">cmd_total</span></code> - Total number of Commands passed through this Session.</p></li>
</ul>
</div>
<divclass="section"id="multisession-mode">
<h2>Multisession mode<aclass="headerlink"href="#multisession-mode"title="Permalink to this headline">¶</a></h2>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE=0</span></code>: One session per account. When connecting with a new session the old one is
disconnected. This is the default mode and emulates many classic mud code bases. In default Evennia,
this mode also changes how the <codeclass="docutils literal notranslate"><spanclass="pre">create</span><spanclass="pre">account</span></code> Command works - it will automatically create a
Character with the <em>same name</em> as the Account. When logging in, the login command is also modified
to have the player automatically puppet that Character. This makes the distinction between Account
and Character minimal from the player’s perspective.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE=1</span></code>: Many sessions per account, input/output from/to each session is treated the
same. For the player this means they can connect to the game from multiple clients and see the same
output in all of them. The result of a command given in one client (that is, through one Session)
will be returned to <em>all</em> connected Sessions/clients with no distinction. This mode will have the
Session(s) auto-create and puppet a Character in the same way as mode 0.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE=2</span></code>: Many sessions per account, one character per session. In this mode,
puppeting an Object/Character will link the puppet back only to the particular Session doing the
puppeting. That is, input from that Session will make use of the CmdSet of that Object/Character and
outgoing messages (such as the result of a <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code>) will be passed back only to that puppeting
Session. If another Session tries to puppet the same Character, the old Session will automatically
un-puppet it. From the player’s perspective, this will mean that they can open separate game clients
and play a different Character in each using one game account.
This mode will <em>not</em> auto-create a Character and <em>not</em> auto-puppet on login like in modes 0 and 1.
Instead it changes how the account-cmdsets’s <codeclass="docutils literal notranslate"><spanclass="pre">OOCLook</span></code> command works so as to show a simple
‘character select’ menu.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE=3</span></code>: Many sessions per account <em>and</em> character. This is the full multi-puppeting
mode, where multiple sessions may not only connect to the player account but multiple sessions may
also puppet a single character at the same time. From the user’s perspective it means one can open
multiple client windows, some for controlling different Characters and some that share a Character’s
input/output like in mode 1. This mode otherwise works the same as mode 2.</p></li>
<p>When you use <codeclass="docutils literal notranslate"><spanclass="pre">msg()</span></code> to return data to a user, the object on which you call the <codeclass="docutils literal notranslate"><spanclass="pre">msg()</span></code> matters. The
<codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE</span></code> also matters, especially if greater than 1.</p>
<p>For example, if you use <codeclass="docutils literal notranslate"><spanclass="pre">account.msg("hello")</span></code> there is no way for evennia to know which session it
should send the greeting to. In this case it will send it to all sessions. If you want a specific
session you need to supply its session to the <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> call (<codeclass="docutils literal notranslate"><spanclass="pre">account.msg("hello",</span><spanclass="pre">session=mysession)</span></code>).</p>
<p>On the other hand, if you call the <codeclass="docutils literal notranslate"><spanclass="pre">msg()</span></code> message on a puppeted object, like
<codeclass="docutils literal notranslate"><spanclass="pre">character.msg("hello")</span></code>, the character already knows the session that controls it - it will
cleverly auto-add this for you (you can specify a different session if you specifically want to send
stuff to another session).</p>
<p>Finally, there is a wrapper for <codeclass="docutils literal notranslate"><spanclass="pre">msg()</span></code> on all command classes: <codeclass="docutils literal notranslate"><spanclass="pre">command.msg()</span></code>. This will
transparently detect which session was triggering the command (if any) and redirects to that session
(this is most often what you want). If you are having trouble redirecting to a given session,
<codeclass="docutils literal notranslate"><spanclass="pre">command.msg()</span></code> is often the safest bet.</p>
<li><p><aclass="reference internal"href="Accounts.html"><spanclass="doc">Accounts</span></a> and <aclass="reference internal"href="Objects.html"><spanclass="doc">Objects</span></a> (including Characters) have a <codeclass="docutils literal notranslate"><spanclass="pre">sessions</span></code> property.
This is a <em>handler</em> that tracks all Sessions attached to or puppeting them. Use e.g.
<codeclass="docutils literal notranslate"><spanclass="pre">accounts.sessions.get()</span></code> to get a list of Sessions attached to that entity.</p></li>
<li><p>A Command instance has a <codeclass="docutils literal notranslate"><spanclass="pre">session</span></code> property that always points back to the Session that triggered
it (it’s always a single one). It will be <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> if no session is involved, like when a mob or
<p>When would one want to customize the Session object? Consider for example a character creation
system: You might decide to keep this on the out-of-character level. This would mean that you create
the character at the end of some sort of menu choice. The actual char-create cmdset would then
normally be put on the account. This works fine as long as you are <codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE</span></code> below 2.
For higher modes, replacing the Account cmdset will affect <em>all</em> your connected sessions, also those
not involved in character creation. In this case you want to instead put the char-create cmdset on
the Session level - then all other sessions will keep working normally despite you creating a new
character in one of them.</p>
<p>By default, the session object gets the <codeclass="docutils literal notranslate"><spanclass="pre">commands.default_cmdsets.UnloggedinCmdSet</span></code> when the user
first connects. Once the session is authenticated it has <em>no</em> default sets. To add a “logged-in”
cmdset to the Session, give the path to the cmdset class with <codeclass="docutils literal notranslate"><spanclass="pre">settings.CMDSET_SESSION</span></code>. This set
will then henceforth always be present as soon as the account logs in.</p>
<p>To customize further you can completely override the Session with your own subclass. To replace the
default Session class, change <codeclass="docutils literal notranslate"><spanclass="pre">settings.SERVER_SESSION_CLASS</span></code> to point to your custom class. This is
a dangerous practice and errors can easily make your game unplayable. Make sure to take heed of the
<aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia/server/session.py">original</a> and make your
<p>Evennia is split into two parts, the <aclass="reference internal"href="Portal-And-Server.html"><spanclass="doc">Portal and the Server</span></a>. Each side tracks
its own Sessions, syncing them to each other.</p>
<p>The “Session” we normally refer to is actually the <codeclass="docutils literal notranslate"><spanclass="pre">ServerSession</span></code>. Its counter-part on the Portal
side is the <codeclass="docutils literal notranslate"><spanclass="pre">PortalSession</span></code>. Whereas the server sessions deal with game states, the portal session
deals with details of the connection-protocol itself. The two are also acting as backups of critical
data such as when the server reboots.</p>
<p>New Account connections are listened for and handled by the Portal using the [protocols](Portal-And-
Server) it understands (such as telnet, ssh, webclient etc). When a new connection is established, a
<codeclass="docutils literal notranslate"><spanclass="pre">PortalSession</span></code> is created on the Portal side. This session object looks different depending on
which protocol is used to connect, but all still have a minimum set of attributes that are generic
<p>These common properties are piped from the Portal, through the AMP connection, to the Server, which
is now informed a new connection has been established. On the Server side, a <codeclass="docutils literal notranslate"><spanclass="pre">ServerSession</span></code> object
is created to represent this. There is only one type of <codeclass="docutils literal notranslate"><spanclass="pre">ServerSession</span></code>; It looks the same
regardless of how the Account connects.</p>
<p>From now on, there is a one-to-one match between the <codeclass="docutils literal notranslate"><spanclass="pre">ServerSession</span></code> on one side of the AMP
connection and the <codeclass="docutils literal notranslate"><spanclass="pre">PortalSession</span></code> on the other. Data arriving to the Portal Session is sent on to
<codeclass="docutils literal notranslate"><spanclass="pre">sessionhandler</span></code>) so they can relay data. See <aclass="reference internal"href="../Concepts/Custom-Protocols.html"><spanclass="doc">protocols</span></a> for more info
<div><p>Note: The <codeclass="docutils literal notranslate"><spanclass="pre">SESSION_HANDLER</span></code> singleton has an older alias <codeclass="docutils literal notranslate"><spanclass="pre">SESSIONS</span></code> that is commonly seen in
