Many-characters-per-Player feature: Asking for testing help

[Griatch Art]

Hi folks,

As of today, the so-called "many-characters-per-player" feature is pretty much feature complete and working. This allows you to play multiple characters using a single Player (account) at the same time! (see Feature Request Issue 279 for original suggestion).

The update has not yet been merged with the main mercural repository. I would appreciate if some adventurous souls would grab the development repository and play with it a bit to report bugs and feedback on it. If you can tell me if the code makes sense to you, even better. You can clone it with the instructions from here:

http://code.google.com/r/griatch-evennia-dev/source/checkout

I recommend not cloning this over your own work directory but to clone into a fresh repo - the migration from a populated main-branch database to the dev one is not yet fully in order. I won't merge it in for a while yet so take the chance to give feedback.


Changes

The many-chars-per-player modification brings with it a slew of changes to the underlying structure - the Player<->Character interaction has been generalized which means some concepts have changed but behind the scenes some things are also occationally cleaned up and easier. On the other hand it also makes the concept of "Session" more prevalent for the developer than it used to be.

Sessions (1 or more)  <->  Player  <-> Puppets/Characters (0 or more)

I will probably need to do an actual graphic for the wiki.

Sessions are the in-game representation of your game connection. If you connect via your mud client, you will be represented by a Session. When you log in, this Session is associated with a Player, which holds all your account info. The Player in turn can puppet Objects. If you log in via another mud client or maybe over the webclient, a new Session will be created to represent this particular connection.


Your settings file now accepts some new variables:

MULTISESSION_MODE=0
This is the same as the old default. Only one session per account is allowed, and only one Puppet/Character. If you log in with another session, the old one will be closed. The default unlogged-in create command will auto-create a Character with the same name as your account and auto-puppet it for you when you connect (it should be noted that almost all of this is in hooks, typeclasses and commands, so you can tweak things as you please without touching the core).
This remains the default since it is so easy to get started. Many games want this type of system anyway.

MULTISESSION_MODE=1
This is equivalent to the old MULTISESSION_MODE=True. It means you can connect with multiple sessions to the same account, but they will all see the same input/output and you will still only be allowed to control one Puppet/Character. Its use is limited IMO but it was not hard to include just for the sake of it.

MULTISESSION_MODE=2
This is the new many-character-per-player mode. You can connect as many Sessions as you want, and each may control their own Puppet/Character. When you log in under this mode you will not auto-connect to a character but will end up at a character creation screen (only superuser will have one character already). A very simplistic @charcreate command is available (you just get to set the name and desc, obviously this is up to you to expand as you like). The @ic/@ooc commands allow you to (for each Session) connect to your available Characters. The session you connect with then alone control that Character (and see its inputs/outputs) until you go @ooc or disconnect. You can connect/disconnect sessions as you please without affecting other sessions. A Server reload will auto-reconnect everything for you behind the scenes. 

MAX_NR_CHARACTERS
This setting limits how many characters you may create (and thus how many Sessions are useful to connect to the same account). It is used by the @charcreate command above and is forced to 1 for MULTISESSION_MODES<2.


Changes behind the scenes

• player.character is no more. The equivalent methods are player.get_puppet(sessid), where sessid is the session id you want to get the puppet object for (this may be None). In fact all reference to "character" is primarily changed to "puppet", since this is more than ever a system for puppet pretty much any Object you have permission to puppet, not only Characters. 
• The lack of a hard-coded link to the Object from the Player side means that puppeting an Object or not only comes down to locks. Whenever un-puppeting (e.g. by using the @ooc command), all links between the Player and Character are severed (before the player.db_obj always remained pointed at a Character). Coincidentally this also means the background logics becomes much more stable and clean and that there is no issue an admin accidentally (and permanently) "taking over" another Player's character. You may not puppet an Object already controlled by an active Player, but otherwise puppet-locks are the only access restriction.
  
• Objects now not only has the obj.player field but also the obj.sessid field for referring back to not only the Player but exactly which session is currently controlling it.
  
• The hooks obj.at_first_login(), at_pre_login(), at_post_login() and at_disconnect() are removed. These make no sense anymore (they need not be called at all during login in MULTISESSION_MODE=2), not to mention the same hooks are available on the Player level anyway - the Player hooks should be used for customizing the login process instead. 
  
• Objects instead have four new hooks related to the act of being connected to the Player, these are obj.at_pre_puppet(player), at_post_puppet(), at_pre_unpuppet() and at_post_unpuppet(player). These have been updated on the default typeclasses and all old functionality duplicated there.
  
• Commands hold a self.sessid property now. Usually this is not something you need to worry about. Using self.caller.msg() will still properly relay data to the right session without you needing to change anything (because of the unique self.sessid field on them).
• Commands on Players however cannot transparently relay msgs to the right Session using the same call as before. So you need to either supply the session in every call or use the new shortcut msg defined directly on the Command base class. Using self.msg() from a Player Command will usually do what you want without extra arguments (there is also a command.msg_contents() etc).
• The Superuser Player can now (under MULTISESSION_MODE=2) have secondary "Test" Characters. Only one Character is designated "superuser character" and has the superuser privileges. The other characters can be assigned any permissions and the Player's superuser flag will not transfer down to them.
  
• Lots of other cleanups and fixes shaking loose when testing this out. The Wiki will be updated with the changed API parts once things go live.
  

Still to do before merging:

• More testing / Code review by other people
  
• Update the examples in game/gamesrc with the changed API
  
• OOCCommands will probably be renamed PlayerCommands and OOCCmdset renamed to PlayerCmdset. It's just a better and more descriptive name. 
• Migrations from populated main branch database are still missing some things.
• Probably other things I've forgotten right now
  

Enjoy!

.

Griatch

[Griatch Art]

Just noting that mere moments after posting the above thread I did add a convenience property player.character for those who want to keep using MULTISESSION_MODE 0/1 and who rely on player.character a lot in their code.
.
Griatch