diff --git a/docs/sphinx/source/wiki/GettingStarted.rst b/docs/sphinx/source/wiki/GettingStarted.rst index 88923610d7..a27f0a7e61 100644 --- a/docs/sphinx/source/wiki/GettingStarted.rst +++ b/docs/sphinx/source/wiki/GettingStarted.rst @@ -49,7 +49,7 @@ Evennia: - The default database system SQLite3 only comes as part of Python2.5 and later. - Windows users are recommended to use ActivePython - (http://www.activestate.com/activepython) + (http://www.activestate.com/activepython/downloads) **Twisted** (http://twistedmatrix.com) @@ -106,19 +106,22 @@ all you need: If some or all dependencies are not readily available (for example, running some flavors of !RedHat/CentOS or an older Debian version) you -can still retrieve them easily by using Python's +can still retrieve them easily by installing and using Python's `easyinstall `_ or the alternative `pip `_: -``easy_install django twisted pil mercurial`` + +:: + + easy_install django twisted pil mercurial :: pip install django twisted pil mercurial **Windows** users may choose to install -`ActivePython `_ instead of the -usual Python. If ActivePython is installed, you can use +`ActivePython `_ +instead of the usual Python. If ActivePython is installed, you can use `pypm `_ in the same manner as ``easy_install``/``pip`` above. This *greatly* simplifies getting started on Windows: @@ -127,8 +130,10 @@ getting started on Windows: pypm install Django Twisted PIL Mercurial -}} Another simple alternative (for all platforms) is to set up a -*virtual Python environment* and install to that. This is covered +Another simple alternative (for all platforms) is to set up a *virtual +Python environment* and install to that - in that case you can even +experiment with different library versions without affecting your main +system configuration. This is covered `here `_. Windows users not using ActivePython or virtual environments will have @@ -257,6 +262,10 @@ To stop Evennia, do: python evennia.py stop +See `Running +Evennia `_ +for more advanced options on controlling Evennia's processes. + Step 4: Connecting to the server -------------------------------- @@ -287,9 +296,10 @@ play. You can install South from available through the normal package distributions, easy\_install, pip, or pypm (see above notes). -Whenever you see a commit or mailing list message instructing you to run -migrations to update your DB schema, simply do the following from within -the ``evennia/game`` directory: +After your first run of ``migrate.py syncdb`` and whenever you see a +commit or mailing list message telling you that "the Database Schema has +changed", simply do the following from within the ``evennia/game`` +directory: :: @@ -325,17 +335,22 @@ virtual environment in here. # for Windows: \bin\activate.bat -In here you can play around and install python packages of any version -without affecting your normal system installation at all. Next we get -all the requirements with *pip*, which comes with virtualenv. This is -the cool bit. +Next we get all the requirements with *pip*, which is included with +virtualenv: :: - pip install django twisted pil + pip install django twisted pil mercurial + +(The difference from the normal install described earlier is that these +installed packages are *only* localized to the virtual environment, they +do not affect the normal versions of programs you run in the rest of +your system. So you could for example experiment with bleeding-edge, +unstable libraries or go back to older versions without having to worry +about messing up other things. It's also very easy to uninstall the +whole thing in one go - just delete your ``mudenv`` folder.) You can now refer to **Step 1** above and continue on from there to -install Evennia into *mudenv* (you need to get ``subversion`` manually -still, it's not a python program). In the future, just go into the -folder and activate it to make this separate virtual environment -available to Evennia. +install Evennia into *mudenv*. In the future, just go into the folder +and activate it to make this separate virtual environment available to +Evennia. diff --git a/docs/sphinx/source/wiki/HelpSystem.rst b/docs/sphinx/source/wiki/HelpSystem.rst index 8802a70425..467d0c4555 100644 --- a/docs/sphinx/source/wiki/HelpSystem.rst +++ b/docs/sphinx/source/wiki/HelpSystem.rst @@ -8,7 +8,7 @@ players and staff alike to learn how to use the game's commands as well as other information pertinent to the game. The help system has many different aspects, from the normal editing of help entries from inside the game, to auto-generated help entries during code development using -the *auto-help* system. +the *auto-help system*. Viewing the help database ------------------------- @@ -31,18 +31,19 @@ Command Auto-help system One important use of the help system is to teach the use of in-game commands. Evennia offers a dynamically updated help system for all your -commands, new and old, known simply as the *auto-help* system. Only -commands that you can actually use are picked up by the auto-help -system. That means an admin will see a considerably larger mass of help -topics when using the ``help`` command than a normal player. +commands, new and old, known simply as the *auto-help system*. Only +commands that you and your character can actually currently use are +picked up by the auto-help system. That means an admin will see a +considerably larger amount of help topics than a normal player when +using the ``help`` command. The auto-help system uses the ``__doc__`` strings of your command definitions and formats this to a nice-looking help entry. This makes for a very easy way to keep the help updated - just document your -commands well - updating the help system is just a ``@reload`` away. -There is no need to manually create help database entries for commands; -as long as you keep the docstrings updated your help will be dynamically -updated for you as well. +commands well abd updating the help file is just a ``@reload`` away. +There is no need to manually create and maintain help database entries +for commands; as long as you keep the docstrings updated your help will +be dynamically updated for you as well. Example (from a module with command definitions): @@ -59,37 +60,38 @@ Example (from a module with command definitions): help_category = "Building" ... -So the text at the very top of the command class definition is the -class' ``__doc__``-string and what will be shown to users looking for -help. Try to use a consistent formatting between your help strings (for -example, all default commands have ``__doc__``-strings formatted in the -way seen above). You should also supply the ``help_category`` class -property if you can; this helps to group help entries together for -easier finding (if you don't supply a help\_category, "General" will be -assumed). +The text at the very top of the command class definition is the class' +``__doc__``-string and will be shown to users looking for help. Try to +use a consistent format - all default commands are using the structure +shown above. You should also supply the ``help_category`` class property +if you can; this helps to group help entries together for easier finding +(if you don't supply a help\_category, "General" will be assumed). Other help entries (entries stored in database) ----------------------------------------------- -The *Other help* section you see when using the ``help`` command shows -all help entries that has been manually added to the database by staff. -Instead of being generated from the code by Evennia, these are stored in -the database using a model called *!HelpEntry*. HelpEntry topics are -intended for world-game-info, tutorials and other types of useful -information not directly tied to a command and covered by auto-help. +Not all help entries concern commands. You will also probably need help +entries describing how your particular game is played - its rules, world +descriptions and other types of information not covered by the auto-help +system. Such entries are manually added to the database by staff and +will appear under a heading "Other help" whenever you have any. Instead +of being generated from the code by Evennia, these entries are stored in +the database as a ``HelpEntry``. A help entry consists of four parts: - The *topic*. This is the name of the help entry. This is what players search for when they are looking for help. The topic can contain - spaces. + spaces and also partual matches will be found. - The *help category*. Examples are *Administration*, *Building*, *Comms* or *General*. This is an overall grouping of similar help topics, used by the engine to give a better overview. -- The *text* - the help text itself, of any length. This can also - include *markup*, see below. -- locks - a `lock definition `_. Help commands check for - access\_types ``examine`` and ``edit``. +- The *text* - the help text itself, of any length. +- locks - a `lock definition `_. This can be used to limit + access to this help entry, maybe because it's staff-only or otherwise + meant to be restricted. Help commands check for ``access_type``s + ``view`` and ``edit``. An example of a lock string would be + ``view:perm(Builders)``. You can create new help entries in code by using ``src.utils.create.create_help_entry()``: @@ -116,11 +118,13 @@ You can change this using a different form of the ``@sethelp`` command: > @sethelp/add emote, Roleplaying = Emoting is important because ... -If the category *Roleplaying* did not exist it is created and will -appear in the help index. You can, finally, define a lock for the help -entry by following the category with a `lock definition `_: +If the category *Roleplaying* did not already exist, it is created and +will appear in the help index. + +You can, finally, define a lock for the help entry by following the +category with a `lock definition `_: :: - > @sethelp/add emote, Roleplaying, view:all() = The emote command ... + > @sethelp/add emote, Roleplaying, view:all() = Emoting is important because ... diff --git a/docs/sphinx/source/wiki/PortalAndServer.rst b/docs/sphinx/source/wiki/PortalAndServer.rst index be5ac31237..ad612a0508 100644 --- a/docs/sphinx/source/wiki/PortalAndServer.rst +++ b/docs/sphinx/source/wiki/PortalAndServer.rst @@ -7,9 +7,9 @@ described `here `_. https://2498159658166209538-a-1802744773732722657-s-sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia*server*portal.png -As seen above, the Server and Portal are glued together via an AMP -(Asynchronous Messaging Protocol) connection. This allows the two -programs to communicate. +The Server and Portal are glued together via an AMP (Asynchronous +Messaging Protocol) connection. This allows the two programs to +communicate. Portal and Server Sessions -------------------------- @@ -24,15 +24,16 @@ Session* 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 to all sessions. -These common properties are piped through AMP to the Server, who is now -informed a new connection has been established. On the Server side, a -*Server Session* object is created to represent this. There is only one -type of Server Session. It looks the same regardless of how the Player -connects, it leaves such details up to the Portal. +These common properties are piped from the Portal, through AMP, to the +*Server*, which is now informed a new connection has been established. +On the Server side, a *Server Session* object is created to represent +this. There is only one type of Server Session. It looks the same +regardless of how the Player connects. From now on, there is a one-to-one match between the Server Session on -one side and the Portal Session on the other. Data arriving to the -Portal Session is sent on to its mirror Server session and vice versa. +one side of the AMP connection and the Portal Session on the other. Data +arriving to the Portal Session is sent on to its mirror Server session +and vice versa. During certain situations, the portal- and server-side sessions are "synced" with each other: @@ -43,12 +44,12 @@ During certain situations, the portal- and server-side sessions are - 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 then +- 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 also not stopped, - obviously). + can survive a server reboot (assuming the Portal is not stopped at + the same time, obviously). Sessionhandlers --------------- diff --git a/docs/sphinx/source/wiki/SessionProtocols.rst b/docs/sphinx/source/wiki/SessionProtocols.rst index e7dd17bdbf..0dac7ed152 100644 --- a/docs/sphinx/source/wiki/SessionProtocols.rst +++ b/docs/sphinx/source/wiki/SessionProtocols.rst @@ -1,8 +1,8 @@ Portal Sessions and Protocols ============================= -*Note: This is considered an advanced topic and not relevant to most -users.* +*Note: This is considered an advanced topic and is mostly of interest to +users planning to implement their own custom client protocol.* A *Portal Session* is the basic data object representing an external connection to the Evennia `Portal `_ -- usually a @@ -40,17 +40,21 @@ A straight-forward protocol (like Telnet) is assumed to at least have the following components (although the actual method names might vary): - ``connectionMade`` - called when a new connection is made. This must - call ``self.init_session()`` with three arguments: an identifier for - the protocol type (e.g. the string 'telnet'), the IP address - connecting, and a reference to the sessionhandler. + call ``self.init_session()`` with three arguments: an *identifier* + for the protocol type (e.g. the string 'telnet' or 'ssh'), the *IP + address* of the client connecting, and a reference to the + *sessionhandler*. The sessionhandler is by convention made available + by storing it on the protocol's *Factory* in + ``src/server/portal.py``, see that file for examples. Doing it this + way avoids many possible recursive import issues. - ``connectionLost`` - called when connection is dropped for whatever - reason. This must call 'self.sessionhandler.disconnect(self)' so the - handler can make sure the disconnect is reported to the rest of the - system. + reason. This must call ``self.sessionhandler.disconnect(self)`` so + the handler can make sure the disconnect is reported to the rest of + the system. - ``getData`` - data arriving from the player to Evennia. This should apply whatever custom formatting this protocol needs, then relay the data to ``self.sessionhandler.data_in(self, msg, data)``. -- sendLine - data from server to Player. This is called by hook +- ``sendLine`` - data from Server to Player. This is called by hook ``data_out()`` below. See an example of this in @@ -58,8 +62,8 @@ See an example of this in These might not be as clear-cut in all protocols, but the principle is there. These four basic components - however they are accessed - links -to the *Session*, which is the actual common interface between the -different low-level protocols and Evennia. +to the *Portal Session*, which is the actual common interface between +the different low-level protocols and Evennia. Portal Sessions --------------- @@ -85,13 +89,15 @@ be named exactly like this): - ``disconnect()`` - called when manually disconnecting. Must call the protocol-specific disconnect method (e.g. ``connectionLost`` above) - ``data_out(string="", data=None)`` - data from Evennia to player. - ``string`` is normally a raw text string with formatting. ``data`` - can be a collection of any extra information the server want to give - to the protocol; it's completely up to the Protocol to handle this - (e.g. telnet completely ignores the ``data`` variable). From inside - Evennia, this if often called with the alias ``msg`` instead. This - method should call the protocol-specific send method, such as - ``self.sendLine()``, directly. + This method should handle any protocol-specific processing before + relaying data on to a send-method like ``self.sendLine()`` mentioned + above. ``string`` is normally a raw text string with formatting. + ``data`` can be a collection of any extra information the server want + to give to the protocol- it's completely up to the Protocol to handle + this. To take an example, telnet assumes ``data`` to be either + ``None`` or a dictionary with flags for how the text should be + parsed. From inside Evennia, ``data_out`` is often called with the + alias ``msg`` instead. Assorted notes -------------- @@ -100,4 +106,6 @@ To take two examples, Evennia supports the *telnet* protocol as well as *webclient*, a custom ajax protocol. You'll find that whereas telnet is a textbook example of a Twisted protocol as seen above, the ajax client protocol looks quite different due to how it interacts with the -webserver through long-polling (comet) style requests. +webserver through long-polling (comet) style requests. All the necessary +parts mentioned above are still there, but implemented in very different +ways.