Finish refactor of components

docs/source/Concepts/Banning.md

@@ -5,10 +5,10 @@ Whether due to abuse, blatant breaking of your rules, or some other reason, you
 no other recourse but to kick out a particularly troublesome player. The default command set has
 admin tools to handle this, primarily `ban`, `unban`, and `boot`. 
 
-## Creating a ban
-
 Say we have a troublesome player "YouSuck" - this is a person that refuses common courtesy - an abusive and spammy account that is clearly created by some bored internet hooligan only to cause grief. You have tried to be nice. Now you just want this troll gone. 
 
+## Creating a ban
+
 ### Name ban
 
 The easiest recourse is to block the account YouSuck from ever connecting again. 
@@ -50,16 +50,6 @@ You should combine the IP ban with a name-ban too of course, so the account YouS
 
 Be careful with too general IP bans however (more asterisks above). If you are unlucky you could be blocking out innocent players who just happen to connect from the same subnet as the offender.
 
-## Booting
-
-YouSuck is not really noticing all this banning yet though - and won't until having logged out and trying to log back in again. Let's help the troll along.
-
-     boot YouSuck
-
-Good riddance. You can give a reason for booting too (to be echoed to the player before getting kicked out).
-
-     boot YouSuck:Go troll somewhere else.
-
 ### Lifting a ban
 
 Use the `unban` (or `ban`) command without any arguments and you will see a list of all currently active bans:
@@ -75,6 +65,17 @@ Use the `id` from this list to find out which ban to lift.
       
     Cleared ban 2: 237.333.0.*
 
+
+## Booting
+
+YouSuck is not really noticing all this banning yet though - and won't until having logged out and trying to log back in again. Let's help the troll along.
+
+     boot YouSuck
+
+Good riddance. You can give a reason for booting too (to be echoed to the player before getting kicked out).
+
+     boot YouSuck:Go troll somewhere else.
+
 ## Summary of abuse-handling tools
 
 Below are other useful commands for dealing with annoying players.

docs/source/Concepts/Concepts-Overview.md

@@ -27,7 +27,7 @@ Text-Encodings.md
 ```{toctree}
 :maxdepth: 2
 
-Multisession-modes.md
+Connection-Styles.md
 Guests.md
 Banning.md
 ```

docs/source/Concepts/Connection-Styles.md

@@ -0,0 +1,90 @@
+# Character connection styles
+
+```shell
+> login Foobar password123
+```
+
+Evennia supports multiple ways for players to connect to the game. This allows Evennia to mimic the behavior of various other servers, or open things up for a custom solution. 
+
+## Changing the login screen
+
+This is done by modifying `mygame/server/conf/connection_screens.py` and reloading. If you don't like the default login, there are two contribs to check out as inspiration.
+
+- [Email login](../Contribs/Contrib-Email-Login.md) - require email during install, use email for login.
+- [Menu login](../Contribs/Contrib-Menu-Login.md) - login using several prompts, asking to enter username and password in sequence.
+
+## Customizing the login command
+
+When a player connects to the game, it runs the `CMD_LOGINSTART` [system command](../Components/Commands.md#system-commands). By default, this is the [CmdUnconnectedLook](evennia.commands.default.unloggedin.CmdUnconnectedLook). This shows the welcome screen. The other commands in the [UnloggedinCmdSet](evennia.commands.default.cmdset_unloggedin.UnloggedinCmdSet) are what defines the login experience. So if you want to customise it, you just need to replace/remove those commands. 
+
+```{sidebar}
+If you instead had your command inherit from `default_cmds.UnConnectedLook`, you didn't even have to speciy the key (since your class would inherit it)!
+```
+```python
+# in mygame/commands/mylogin_commands.py
+
+from evennia import syscmdkeys, default_cmds, Command
+
+
+class MyUnloggedinLook(Command):
+
+    # this will now be the first command called when connecting
+    key = syscmdkeys.CMD_LOGINSTART 
+
+    def func(self):
+        # ... 
+```
+ 
+Next, add this to the right place in the `UnloggedinCmdSet`: 
+
+```python
+# in mygame/commands/default_cmdsets.py
+
+from commands.mylogin_commands import MyUnloggedinLook
+# ... 
+
+class UnloggedinCmdSet(default_cmds.UnloggedinCmdSet):
+    # ... 
+    def at_cmdset_creation(self):
+        super().at_cmdset_creation
+        self.add(MyUnloggedinLook())
+```
+
+`reload` and your alternate command will be used. Examine the default commands and you'll be able to change everything about the login. 
+
+## Multisession mode and multi-playing
+
+The multisession modes are described in detail in the [Session documentation](../Components/Sessions.md#multisession-mode). In brief, this is controlled by a [setting](../Setup/Settings.md). Here's the default: 
+
+    MULTISESSION_MODE = 0
+
+- `MULTISESSION_MODE=0`: One [Session](../Components/Sessions.md) per [Account](../Components/Accounts.md), routed to one [puppet](../Components/Objects.md). If connecting with a new session/client, it will kick the previous one. 
+- `MULTISESSION_MODE=1`: Multiple sessions per Account, all routed to one puppet. Allows you to control one puppet from multiple client windows.
+- `MULTISESSION_MODE=2`: Multiple sessions per Account, each routed to a different puppet. This allows for multi-playing.
+- `MULTISESSION_MODE=3`: Multiple sessions per account, And multiple sessions per puppet. This is full multi-playing, including being able to control each puppet from multiple clients.
+
+Mode `0` is the default and mimics how many legacy codebases work, especially in the DIKU world. The equivalence of higher modes are often 'hacked' into existing servers to allow for players to have multiple characters. 
+
+    MAX_NR_SIMULTANEOUS_PUPPETS = 1
+
+This setting limits how many _different_ puppets your _Account_ can puppet _simultaneously_. This is used to limit true multiplaying. A value higher than one makes no sense unless `MULTISESSION_MODE` is also set `>1`.  Set to `None` for no limit.
+
+## Character creation and auto-puppeting
+
+When a player first creates an account, Evennia will auto-create a `Character` puppet of the same name. When the player logs in, they will auto-puppet this Character. This default hides the Account-Character separation from the player and puts them immediately in the game. This default behavior is similar to how it works in many legacy MU servers. 
+
+To control this behavior, you need to tweak the settings. These are the defaults: 
+
+    AUTO_CREATE_CHARACTER_WITH_ACCOUNT = True
+    AUTO_PUPPET_ON_LOGIN = True 
+    MAX_NR_CHARACTERS = 1
+    
+There is a default `charcreate` command. This heeds the `MAX_NR_CHARACTERS`; and if you make your own character-creation command, you should do the same. It needs to be at least `1`. Set to `None` for no limit. See the [Beginner Tutorial](../Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview.md) for ideas on how to make a more advanced character generation system.
+
+```{sidebar}
+Combining these settings with `MAX_NR_SIMULTANEOUS_PUPPETS` could allow for a game where (for example) a player can create a 'stable' of Characters, but only be able to play one at a time. 
+```
+If you choose to not auto-create a character, you will need to provide a character-generation, and there will be no (initial) Character to puppet. In both of these settings, you will initially end up in  `ooc` mode after you login. This is a good place to put a character generation screen/menu (you can e.g. replace the [CmdOOCLook](evennia.commands.default.account.CmdOOCLook) to trigger something other than the normal ooc-look). 
+
+Once you created a Character, if your auto-puppet is set, you will automatically puppet your latest-puppeted Character whenever you login. If not set, you will always start OOC (and should be able to select which Character to puppet).
+

docs/source/Concepts/Guests.md

@@ -1,29 +1,18 @@
 # Guest Logins
 
 
-Evennia supports *guest logins* out of the box. A guest login is an anonymous, low-access account
-and can be useful if you want users to have a chance to try out your game without committing to
-creating a real account.
+Evennia supports *guest logins* out of the box. A guest login is an anonymous, low-access account and can be useful if you want users to have a chance to try out your game without committing to creating a real account. 
 
 Guest accounts are turned off by default. To activate, add this to your `game/settings.py` file:
 
     GUEST_ENABLED = True
 
-Henceforth users can use `connect guest` (in the default command set) to login with a guest account.
-You may need to change your [Connection Screen](../Components/Connection-Screen.md) to inform them of this
-possibility. Guest accounts work differently from normal accounts - they are automatically *deleted*
-whenever the user logs off or the server resets (but not during a reload). They are literally re-
-usable throw-away accounts.
+Henceforth users can use `connect guest` (in the default command set) to login with a guest account. You may need to change your [Connection Screen](../Components/Connection-Screen.md) to inform them of this possibility. Guest accounts work differently from normal accounts - they are automatically *deleted* whenever the user logs off or the server resets (but not during a reload). They are literally re- usable throw-away accounts.
 
 You can add a few more variables to your `settings.py` file to customize your guests:
 
-- `BASE_GUEST_TYPECLASS` - the python-path to the default [typeclass](../Components/Typeclasses.md) for guests.
-Defaults to `"typeclasses.accounts.Guest"`.
-- `PERMISSION_GUEST_DEFAULT` - [permission level](../Components/Locks.md) for guest accounts. Defaults to `"Guests"`,
-which is the lowest permission level in the hierarchy.
-- `GUEST_START_LOCATION` - the `#dbref` to the starting location newly logged-in guests should
-appear at. Defaults to `"#2` (Limbo).
+- `BASE_GUEST_TYPECLASS` - the python-path to the default [typeclass](../Components/Typeclasses.md) for guests. Defaults to `"typeclasses.accounts.Guest"`.
+- `PERMISSION_GUEST_DEFAULT` - [permission level](../Components/Locks.md) for guest accounts. Defaults to `"Guest"`, which is the lowest permission level in the hierarchy (below `Player`).
+- `GUEST_START_LOCATION` - the `#dbref` to the starting location newly logged-in guests should appear at. Defaults to `"#2` (Limbo).
 - `GUEST_HOME` - guest home locations. Defaults to Limbo as well.
-- `GUEST_LIST` - this is a list holding the possible guest names to use when entering the game. The
-length of this list also sets how many guests may log in at the same time. By default this is a list
-of nine names from `"Guest1"` to `"Guest9"`.
+- `GUEST_LIST` - this is a list holding the possible guest names to use when entering the game. The length of this list also sets how many guests may log in at the same time. By default this is a list of nine names from `"Guest1"` to `"Guest9"`.

docs/source/Concepts/Multisession-modes.md

@@ -1,3 +0,0 @@
-# Multisession modes 
-
-TODO: This is covered in various places before.

docs/source/Concepts/Zones.md

@@ -1,5 +1,6 @@
 # Zones
 
+Evennia recommends using [Tags](../Components/Tags.md) to create zones and other groupings. 
 
 Say you create a room named *Meadow* in your nice big forest MUD.  That's all nice and dandy, but
 what if you, in the other end of that forest want another *Meadow*? As a game creator, this can
@@ -15,26 +16,21 @@ simply find all rooms that are "magical" so you could send messages to them.
 
 ## Zones in Evennia
 
-*Zones* try to separate rooms by global location. In our example we would separate the forest into
-two parts - the magical and the non-magical part. Each have a *Meadow* and rooms belonging to each
-part should be easy to retrieve.
+*Zones* try to separate rooms by global location. In our example we would separate the forest into two parts - the magical and the non-magical part. Each have a *Meadow* and rooms belonging to each part should be easy to retrieve.
 
 Many MUD codebases hardcode zones as part of the engine and database.  Evennia does no such
-distinction due to the fact that rooms themselves are meant to be customized to any level anyway.
-Below is a suggestion for how to implement zones in Evennia.
+distinction.
 
-All objects in Evennia can hold any number of [Tags](../Components/Tags.md). Tags are short labels that you attach to
-objects. They make it very easy to retrieve groups of objects. An object can have any number of
-different tags. So let's attach the relevant tag to our forest:
+All objects in Evennia can hold any number of [Tags](../Components/Tags.md). Tags are short labels that you attach to objects. They make it very easy to retrieve groups of objects. An object can have any number of different tags. So let's attach the relevant tag to our forest: 
 
 ```python
      forestobj.tags.add("magicalforest", category="zone")
 ```
 
 You could add this manually, or automatically during creation somehow (you'd need to modify your
-@dig command for this, most likely). You can also use the default `@tag` command during building:
+`dig` command for this, most likely). You can also use the default `tag` command during building:
 
-     @tag forestobj = magicalforest : zone
+     tag forestobj = magicalforest : zone
 
 Henceforth you can then easily retrieve only objects with a given tag:
 
@@ -45,11 +41,7 @@ Henceforth you can then easily retrieve only objects with a given tag:
 
 ## Using typeclasses and inheritance for zoning
 
-The tagging or aliasing systems above don't instill any sort of functional difference between a
-magical forest room and a normal one - they are just arbitrary ways to mark objects for quick
-retrieval later. Any functional differences must be expressed using [Typeclasses](../Components/Typeclasses.md).
+The tagging or aliasing systems above don't instill any sort of functional difference between a magical forest room and a normal one - they are just arbitrary ways to mark objects for quick retrieval later. Any functional differences must be expressed using [Typeclasses](../Components/Typeclasses.md). 
 
-Of course, an alternative way to implement zones themselves is to have all rooms/objects in a zone
-inherit from a given typeclass parent - and then limit your searches to objects inheriting from that
-given parent. The effect would be similar but you'd need to expand the search functionality to
+Of course, an alternative way to implement zones themselves is to have all rooms/objects in a zone inherit from a given typeclass parent - and then limit your searches to objects inheriting from that given parent. The effect would be similar but you'd need to expand the search functionality to
 properly search the inheritance tree.