Use call_hook_function() in handler_active()

[mudpy.git] / doc / source / configuration.rst

===============
 configuration
===============

.. Copyright (c) 2004-2019 mudpy authors. Permission to use, copy,
   modify, and distribute this software is granted under terms
   provided in the LICENSE file distributed with this software.

.mudpy.filing
-------------

.mudpy.filing.groups
~~~~~~~~~~~~~~~~~~~~

dict, optional

Each item in the dict identifies options for the default backing
file of the group named in its key. The value is itself a dict with
its keys and values corresponding to those options (for now, only
``flags`` is implemented, with a value of ``private`` indicating it
should be readable only by the system user under which the mudpy
process is running).

Example::

  .mudpy.filing.groups:
      account:
          flags:
              - private

.mudpy.filing.prefix
~~~~~~~~~~~~~~~~~~~~

string, optional

This is the root path beneath which all relative file references,
including directories comprising the search path, are assumed to be
found. The default value of ``.`` indicates the current working
directory at the time the service was initially started.

Example::

  .mudpy.filing.prefix: .

.mudpy.filing.search
~~~~~~~~~~~~~~~~~~~~

list, required

Directories to search for expected data files. If not a fully
canonical path, this is assumed to be relative to the ``prefix``.

Example::

  .mudpy.filing.search:
      - ""
      - etc
      - share
      - data

.mudpy.filing.stash
~~~~~~~~~~~~~~~~~~~

string, required

This is the default directory where new data files will be written
if their full paths are not specified and they aren't already found
in the ``search`` list. If not a fully canonical path, this is
assumed to be relative to the ``prefix``.

Example::

  .mudpy.filing.stash: data

.mudpy.linguistic
-----------------

.mudpy.linguistic.actions
~~~~~~~~~~~~~~~~~~~~~~~~~

dict, optional

This is used to tailor the appearance of output generated by the
``say`` command and its relatives, so as to add some readability and
flavor. It matches a visible action to punctuation (ask, exclaim, et
cetera).

Example::

  .mudpy.linguistic.actions:
      ?: ask
      ",": begin
      -: begin
      :: begin
      ;: begin
      "!": exclaim
      ...: muse
      .: say

.mudpy.linguistic.default_punctuation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

string, optional

Unpunctuated statements made by actors should be assumed to
terminate with this value.

Example::

  .mudpy.linguistic.default_punctuation: .

.mudpy.linguistic.typos
~~~~~~~~~~~~~~~~~~~~~~~

dict, optional

Replacements for common typographical and capitalization errors.

Example::

  .mudpy.linguistic.typos:
      i: I
      i'd: I'd
      i'll: I'll
      i'm: I'm
      teh: the
      theyre: they're
      youre: you're

.mudpy.limit
------------

.mudpy.limit.admins
~~~~~~~~~~~~~~~~~~~

list, optional

The first users to create accounts with names in this list will
automatically be given full administrative privileges.

Example::

  .mudpy.limit.admins:
      - admin

.mudpy.limit.avatars
~~~~~~~~~~~~~~~~~~~~

int, required

This is the maximum number of avatars allowed for each account.

Example::

  .mudpy.limit.avatars: 7

.mudpy.limit.backups
~~~~~~~~~~~~~~~~~~~~

int, optional

This is the number of backups to keep and rotate when overwriting
data files. If unspecified or set to 0, no backup copies will be
made.

Example::

  .mudpy.limit.backups: 10

.mudpy.limit.password_tries
~~~~~~~~~~~~~~~~~~~~~~~~~~~

int, required

This is the maximum number of password failures allowed during the
login process. Once exceeded, the user will be disconnected.

Example::

  .mudpy.limit.password_tries: 3

.mudpy.log
----------

.mudpy.log.file
~~~~~~~~~~~~~~~

string, optional

If set, log messages will be recorded to this file.

Example::

  .mudpy.log.file: var/mudpy.log

.mudpy.log.lines
~~~~~~~~~~~~~~~~

int, optional

Number of log entries to keep in memory (the oldest are
discarded)... If unset or 0, none will be written to mudpy's
internal memory.

Example::

  .mudpy.log.lines: 1000

.mudpy.log.stdout
~~~~~~~~~~~~~~~~~

bool, optional

If set to ``yes``, messages will be logged to the standard output of
the mudpy process. If unspecified, the default is ``no``.

Example::

  .mudpy.log.stdout: true

.mudpy.log.syslog
~~~~~~~~~~~~~~~~~

string, optional

If set, mudpy will send messages to the system log, and under the
name specified by this value (Unix derivatives only).

Example::

  .mudpy.log.syslog: mudpy

.mudpy.movement
---------------

.mudpy.movement.*.enter_term
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

string, multiple

Word or words describing the direction from where you are seen to
enter the next room when moving.

Example::

  .mudpy.movement.down.enter_term: above
  .mudpy.movement.east.enter_term: the west
  .mudpy.movement.north.enter_term: the south
  .mudpy.movement.south.enter_term: the north
  .mudpy.movement.up.enter_term: below
  .mudpy.movement.west.enter_term: the east

.mudpy.movement.*.exit_term
~~~~~~~~~~~~~~~~~~~~~~~~~~~

string, multiple

Word or words describing the direction where you are seen to exit
the current room when moving.

Example::

  .mudpy.movement.down.exit_term: downward
  .mudpy.movement.east.exit_term: to the east
  .mudpy.movement.north.exit_term: to the north
  .mudpy.movement.south.exit_term: to the south
  .mudpy.movement.up.exit_term: upward
  .mudpy.movement.west.exit_term: to the west

.mudpy.movement.*.vector
~~~~~~~~~~~~~~~~~~~~~~~~

triplet, multiple

Vector of signed integer units for use in vector addition to derive
the destination coordinates from the current coordinates when moving
through a gridlink exit. The example coordinate system used is left
handed (east, north and up are positive, west, south and down are
negative) and three-dimensional with a tuple component order of
(longitude, latitude, altitude).

Example::

  .mudpy.movement.down.vector: [0, 0, -1]
  .mudpy.movement.east.vector: [1, 0, 0]
  .mudpy.movement.north.vector: [0, 1, 0]
  .mudpy.movement.south.vector: [0, -1, 0]
  .mudpy.movement.up.vector: [0, 0, 1]
  .mudpy.movement.west.vector: [-1, 0, 0]

.mudpy.network
--------------

.mudpy.network.host
~~~~~~~~~~~~~~~~~~~

string, optional

The IP address on which to listen. If unspecified, the default is
all available addresses.

Example::

  .mudpy.network.host: ::1

.mudpy.network.port
~~~~~~~~~~~~~~~~~~~

int, required

The TCP port on which to listen.

Example::

  .mudpy.network.port: 4000

.mudpy.process
--------------

.mudpy.process.daemon
~~~~~~~~~~~~~~~~~~~~~

bool, optional

If set to ``yes``, mudpy will immediately fork and detach a child to
become a daemon process, then close all open file descriptors and
terminate the parent process (Unix derivatives only). The default
value is ``no``.

Example::

  .mudpy.process.daemon: true

.mudpy.process.pidfile
~~~~~~~~~~~~~~~~~~~~~~

string, optional

If set, this filename will contain the daemon's process ID (Unix
derivatives only).

Example::

  .mudpy.process.pidfile: var/mudpy.pid

.mudpy.timing
-------------

.mudpy.timing.idle.disconnect.*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

int, multiple

This value indicates the number of increments allowed to pass
without input on a socket connection before it is terminated. This
avoids accumulation of dead sockets which could otherwise max out
allowed file descriptors. The differentiators are either ``default``
or a state name used to override the default value for that specific
state (``active``, ``entering_account_name``, et cetera).

Example::

  .mudpy.timing.idle.disconnect.active: 6048000
  .mudpy.timing.idle.disconnect.default: 6000
  .mudpy.timing.idle.disconnect.entering_account_name: 600

.mudpy.timing.idle.warn.*
~~~~~~~~~~~~~~~~~~~~~~~~~

int, multiple

This value indicates the number of increments allowed to pass
without input on a socket connection before it is warned that
termination is imminent. The differentiators are either
``default`` or a state name used to override the default value
for that specific state. It is recommended that this be less than
the corresponding ``.mudpy.timing.idle.disconnect.*`` value.

Example::

  .mudpy.timing.idle.warn.active: 5040000
  .mudpy.timing.idle.warn.default: 5000
  .mudpy.timing.idle.warn.entering_account_name: 500

.mudpy.timing.increment
~~~~~~~~~~~~~~~~~~~~~~~

float, required

This value indicates the number of real system clock seconds (or
more commonly, fraction thereof) each pass through the main loop is
intended to take. This roughly sets the frequency with which queued
socket I/O operations are performed, pending events are triggered,
and directly impacts the speed at which virtual time passes within
the simulation.

Example::

  .mudpy.timing.increment: 0.1

.mudpy.timing.save
~~~~~~~~~~~~~~~~~~

int, required

Number of increments between updates of changed persistent data
storage.

Example::

  .mudpy.timing.save: 600

.mudpy.timing.status
~~~~~~~~~~~~~~~~~~~~

int, optional

Number of increments to wait between logging mudpy status messages.
If unspecified or set to 0, no mudpy status messages will be
written.

Example::

  .mudpy.timing.status: 6000

.mudpy.user
-----------

.mudpy.user.pref_admin
~~~~~~~~~~~~~~~~~~~~~~

list, optional

This can be used to list facets an administrative user is allowed to
set or override on their own ``account`` element, in addition to any
in the `.mudpy.user.pref_allow`_ list. Note that this is merely a
convenience, as an administrator is already able to call the ``set``
command to set values for facets of any element.

Example::

  .mudpy.user.pref_admin:
      - loglevel

.mudpy.user.pref_allow
~~~~~~~~~~~~~~~~~~~~~~

list, optional

This can be used to list facets any user is allowed to set or
override on their own ``account`` element with the ``preference``
command.

Example::

  .mudpy.user.pref_allow:
      - prompt