mirror of
https://github.com/evennia/evennia.git
synced 2026-03-16 21:06:30 +01:00
103 lines
5.3 KiB
ReStructuredText
103 lines
5.3 KiB
ReStructuredText
Batch Processors - overview
|
|
===========================
|
|
|
|
Building a game world is a lot of work, especially when starting out.
|
|
Rooms should be created, descriptions have to be written, objects must
|
|
be detailed and placed in their proper places. In many traditional MUD
|
|
setups you had to do all this online, line by line, over a telnet
|
|
session.
|
|
|
|
Evennia already moves away from much of this by shifting the main coding
|
|
work to external Python modules. But also building would be helped if
|
|
one could do some or all of it externally. Enter Evennia's *batch
|
|
command processors* (there are two of them). The processors allows you,
|
|
as a game admin, to build your game completely offline in normal text
|
|
files (*batch files*) that the processors understands. Then, when you
|
|
are ready, you use the processors to read it all into Evennia (and into
|
|
the database) in one go.
|
|
|
|
You can of course still build completely online should you want to -
|
|
this is certainly the easiest way to go when learning and for small
|
|
build projects. But for major building work, the advantages of using the
|
|
batch-processors are many:
|
|
|
|
- It's hard to compete with the comfort of a modern desktop text
|
|
editor; Compared to a traditional MUD line input, you can get much
|
|
better overview and many more features. Also, accidentally pressing
|
|
Return won't immediately commit things to the database.
|
|
- You might run external spell checkers on your batch files. In the
|
|
case of one of the batch-processors (the one that deals with Python
|
|
code), you could also run external debuggers and code analyzers on
|
|
your file to catch problems before feeding it to Evennia.
|
|
- The batch files (as long as you keep them) are records of your work.
|
|
They make a natural starting point for quickly re-building your world
|
|
should you ever decide to start over.
|
|
- If you are an Evennia developer, using a batch file is a fast way to
|
|
setup a test-game after having reset the database.
|
|
- The batch files might come in useful should you ever decide to
|
|
distribute all or part of your world to others.
|
|
|
|
There are two batch processors, the Batch-*command* processor and the
|
|
Batch-*code* processor. The first one is the simpler of the two. It has
|
|
the advantage of you not needing to know any programming - you basically
|
|
just list game commands in a text file. The code-processor on the other
|
|
hand is much more powerful but also more complex - it lets you to use
|
|
Evennia's API to code your world in full-fledged Python code.
|
|
|
|
- The `Batch-command processor <BatchCommandProcessor.html>`_
|
|
- The `Batch-code processor <BatchCodeProcessor.html>`_
|
|
|
|
If you plan to use international characters in your batchfiles you are
|
|
wise to read about *file encodings* below.
|
|
|
|
A note on File Encodings
|
|
------------------------
|
|
|
|
As mentioned, both the processors take text files as input and then
|
|
proceeds to process them. As long as you stick to the standard
|
|
`ASCII <http://en.wikipedia.org/wiki/Ascii>`_ character set (which means
|
|
the normal English characters, basically) you should not have to worry
|
|
much about this section.
|
|
|
|
Many languages however use characters outside the simple ``ASCII``
|
|
table. Common examples are various apostrophes and umlauts but also
|
|
completely different symbols like those of the greek or cyrillic
|
|
alphabets.
|
|
|
|
First, we should make it clear that Evennia itself handles international
|
|
characters just fine. It (and Django) uses
|
|
`unicode <http://en.wikipedia.org/wiki/Unicode>`_ strings internally.
|
|
|
|
The problem is that when reading a text file like the batchfile, we need
|
|
to know how to decode the byte-data stored therein to universal unicode.
|
|
That means we need an *encoding* (a mapping) for how the file stores its
|
|
data. There are many, many byte-encodings used around the world, with
|
|
opaque names such as ``Latin-1``, ``ISO-8859-3`` or ``ARMSCII-8`` to
|
|
pick just a few examples. Problem is that it's practially impossible to
|
|
determine which encoding was used to save a file just by looking at it
|
|
(it's just a bunch of bytes!). You have to *know*.
|
|
|
|
With this little introduction it should be clear that Evennia can't
|
|
guess but has to *assume* an encoding when trying to load a batchfile.
|
|
The text editor and Evennia must speak the same "language" so to speak.
|
|
Evennia will by default first try the international ``UTF-8`` encoding,
|
|
but you can have Evennia try any sequence of different encodings by
|
|
customizing the ``ENCODINGS`` list in your settings file. Evennia will
|
|
use the first encoding in the list that do not raise any errors. Only if
|
|
none work will the server give up and return an error message.
|
|
|
|
You can often change the text editor encoding (this depends on your
|
|
editor though), otherwise you need to add the editor's encoding to
|
|
Evennia's ``ENCODINGS`` list. If you are unsure, write a test file with
|
|
lots of non-ASCII letters in the editor of your choice, then import to
|
|
make sure it works as it should.
|
|
|
|
More help with encodings can be found in the entry `Text
|
|
Encodings <TextEncodings.html>`_ and also in the Wikipedia article
|
|
`here <http://en.wikipedia.org/wiki/Text_encodings>`_.
|
|
|
|
**A footnote for the batch-code processor**: Just because *Evennia* can
|
|
parse your file and your fancy special characters, doesn't mean that
|
|
*Python* allows their use. Python syntax only allows international
|
|
characters inside *strings*. In all other source code only ``ASCII`` set
|
|
characters are allowed.
|