An Evennia Session 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.
A session object has its own cmdset, usually the “unloggedin” cmdset. This is what is used to show the login screen and to handle commands to create a new account (or Player in evennia lingo) read initial help and to log into the game with an existing account.
Warning: A Session is not persistent - it is not a typeclass 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
.dbhandler on Sessions is there to present a uniform API, but if you were to read its doc you’ll find it’s actually just an alias to
.ndb. So don’t store any data on Sessions that you can’t afford to lose in a reload. You have been warned.
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 a Player object (which is what holds account-centric stuff). The player can then in turn puppet any number of objects/characters.
The number of sessions possible to connect to a given player at the same
time and how it works is given by the
MULTISESSION_MODE=0: One session per player. When connecting with a new session the old one is disconneted. This is the default mode and emulates many classic mud code bases.
MULTISESSION_MODE=1: Many sessions per player, input from each session is treated identically. This means that you could use any number of different clients to input something and all would see the same result back.
MULTISESSION_MODE=2: Many sessions per player, one character per session. This is the multi-playing mode where each session may, through one player account, individually puppet its own object/character without affecting what happens in other sessions.
MULTIPLAYER_MODE=3: Many sessions per player and 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. Tt is a multi-session version of mode 1. This allows multiplaying of many characters from any number of clients at once.
Returning data to the session¶
When you use
msg() to return data to a user, the object on which you
msg() matters. The
MULTISESSION_MODE also matters,
especially if greater than 1.
For example, if you use
player.msg("hello") 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 id (
sessid) to the
On the other hand, if you call the
msg() message on a puppeted
character.msg("hello"), the character already knows the
sessid of the session that controls it - it will cleverly auto-add this
for you (you can specify a different sessid if you specifically want to
send stuff to another session).
Finally, there is a wrapper for
msg() on all command classes:
command.msg(). 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
command.msg() is often the safest bet.
You can get the
sessid in many ways.
- A session stores the sessid in a property
- The player’s
sessionsproperty holds all sessions connected to this player.
- Puppeted objects (normally Characters) have the persistent
sessidproperty of the session puppeting them.
- Commands store the
sessidpointing back to the session that triggered them (will be
Noneif no session is involved, like when a mob or script triggers the command).
Customizing the session object¶
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 player. This works fine as long
as you are
MULTISESSION_MODE below 2. For higher modes, replacing
the Player cmdset will affect all 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
By default, the session object gets the
commands.default_cmdsets.UnloggedinCmdSet when the user first
connects. Once the session is authenticated it has no default sets. To
add a “logged-in” cmdset to the Session, give the path to the cmdset
settings.CMDSET_SESSION. This set will then henceforth
always be present as soon as the player logs in.
To customize further you can completely override the Session with your
own subclass. To replace the default Session class, change
settings.SERVER_SESSION_CLASS 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 original and make your changes
Portal and Server Sessions¶
Note: This is considered an advanced topic. You don’t need to know this on a first read-through.
Evennia is split into two parts, the Portal and the Server. Each side tracks its own Sessions, syncing them to each other.
The “Session” we normally refer to is actually the
Its counter-part on the Portal side is the
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.
PortalSessionis 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 to all
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
ServerSession object is
created to represent this. There is only one type of
It looks the same regardless of how the Player connects.
From now on, there is a one-to-one match between the
on one side of the AMP connection and the
PortalSession on the
other. Data arriving to the Portal Session is sent on to its mirror
Server session and vice versa.
- The Player closes their client, killing the Portal Session. The Portal syncs with the Server to make sure the corresponding Server Session is also deleted.
- The Player quits from inside the game, killing the Server Session. The Server then syncs with the Portal to make sure to close the Portal connection cleanly.
- The Server is rebooted/reset/shutdown - The Server Sessions are copied over (“saved”) to the Portal side. When the Server comes back up, this data is returned by the Portal so the two are again in sync. This way a Player’s login status and other connection-critical things can survive a server reboot (assuming the Portal is not stopped at the same time, obviously).
sessionhandler) so they can relay data. See protocols for more info