5 .. Copyright (c) 2004-2018 mudpy authors. Permission to use, copy,
6 modify, and distribute this software is granted under terms
7 provided in the LICENSE file distributed with this software.
9 One of the primary goals for mudpy is to apply a consistent data
10 model for all information, from configuration and preferences to
11 user accounts and world data. Individual pieces of information are
12 called *facets*, and are grouped together into entities called
13 *elements*. Elements are meant to be treated as loosely-typed
14 objects (if it walks like a duck and talks like a duck...), while
15 facets within them have predefined names and are strictly typed.
16 This combination provides the ability to have facet inheritance
17 among elements as a layered sieve.
19 The mudpy data model consists of a mix of persistent data (stored
20 externally but cached in memory), and ephemeral data
21 (cross-reference indexes which can be regenerated from it). For now,
22 persistent data is stored externally in a tree-like hierarchy of
23 text files starting from a main configuration usually named
24 mudpy.yaml and cached in memory as a single python dict known as the
25 *universe*. This default implementation, while memory-hungry, is
26 planned so as to reduce the number of dict lookup operations
27 performed to retrieve an individual piece of information, when
28 compared with a more deeply-nested dict model.
33 The universe is organized with a hierarchical namespace using the
34 period (``.``) symbol as a separator. It is rooted at ``.`` and
35 grows to the right with successive nodes. The right-most node must
36 always be a facet, and the remainder of the series thus denotes the
37 absolute name of an element within the universe (the second node
38 from the right being the relative element name and the remaining
39 nodes to the left are called the *group*). Near the root of the
40 universal namespace are a number of special elements anchored within
41 the ``.mudpy`` branch which provide necessary configuration
42 information and keeps some basic elements from cluttering the rest
48 Where new actor elements with no specified storage destination are
55 Where the default archetype definitions are grouped together.
60 Where the default command definitions are grouped together.
65 Defines default long-term storage locations for various element
71 Defines default values and validation checks for every facet.
76 Defines filesystem-based backend storage meta data.
81 Language specific configuration.
86 Various aspects determining mudpy performance.
91 Configuration for logging.
96 Where the default menu definitions are grouped together.
101 Defines movement directions.
106 Network socket configuration.
111 Process-specific configuration.
116 Where new prop elements with no specified storage destination are
122 Where new room elements with no specified storage destination are
128 Timing-specific settings and scheduling for the main loop.
133 Long-term storage is accomplished with YAML format files, consisting
134 of an associative array of keys mapped to values of various data
135 types. The keys can be either absolute (beginning with a ``.``
136 character) or relative to the anchor specified by the parent file
137 which loaded it. Special records can also exist to describe a data
138 file's properties, and always begin with an underscore (``_``).
139 These are stored in the universe under the ``.mudpy.file`` group
140 with elements named for escaped versions of the file path (``.`` and
141 ``:`` replaced by ``\.`` and ``\:``) and the underscore stripped
142 from the beginning of each facet.
147 Arbitrary string providing copyright notice and license information.
152 Arbitrary string containing a description of the file or any other
153 useful information worth noting.
158 List of additional data sources to load and where to anchor their
159 elements in the universe. The value is prefaced by the storage
160 medium separated from the remainder by an optional parenthetical
161 parameter and a colon. The only type implemented so far is ``file``
162 and the optional parameter is ``p`` to indicate a private file which
163 should only be readable by the account under which the process is
164 running rather than created with the default umask (ignored on
165 unsupported platforms).
170 Boolean value indicating read-only status. Any file not protected
171 with a _lock record will be regenerated and rewritten by mudpy if
172 its records are changed, so record format will be normalized,
173 records arbitrarily reordered and YAML comments lost in the process.