Rename debug testenv to demo and use sample config
[mudpy.git] / doc / source / configuration.rst
1 ===============
2  configuration
3 ===============
4
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.
8
9 .mudpy.filing
10 -------------
11
12 .mudpy.filing.groups
13 ~~~~~~~~~~~~~~~~~~~~
14
15 dict, optional
16
17 Each item in the dict identifies options for the default backing
18 file of the group named in its key. The value is itself a dict with
19 its keys and values corresponding to those options (for now, only
20 ``flags`` is implemented, with a value of ``private`` indicating it
21 should be readable only by the system user under which the mudpy
22 process is running).
23
24 Example::
25
26   .mudpy.filing.groups:
27       account:
28           flags:
29               - private
30
31 .mudpy.filing.prefix
32 ~~~~~~~~~~~~~~~~~~~~
33
34 string, optional
35
36 This is the root path beneath which all relative file references,
37 including directories comprising the search path, are assumed to be
38 found. The default value of ``.`` indicates the current working
39 directory at the time the service was initially started.
40
41 Example::
42
43   .mudpy.filing.prefix: .
44
45 .mudpy.filing.search
46 ~~~~~~~~~~~~~~~~~~~~
47
48 list, required
49
50 Directories to search for expected data files. If not a fully
51 canonical path, this is assumed to be relative to the ``prefix``.
52
53 Example::
54
55   .mudpy.filing.search:
56       - ""
57       - etc
58       - share
59       - data
60
61 .mudpy.filing.stash
62 ~~~~~~~~~~~~~~~~~~~
63
64 string, required
65
66 This is the default directory where new data files will be written
67 if their full paths are not specified and they aren't already found
68 in the ``search`` list. If not a fully canonical path, this is
69 assumed to be relative to the ``prefix``.
70
71 Example::
72
73   .mudpy.filing.stash: data
74
75 .mudpy.linguistic
76 -----------------
77
78 .mudpy.linguistic.actions
79 ~~~~~~~~~~~~~~~~~~~~~~~~~
80
81 dict, optional
82
83 This is used to tailor the appearance of output generated by the
84 ``say`` command and its relatives, so as to add some readability and
85 flavor. It matches a visible action to punctuation (ask, exclaim, et
86 cetera).
87
88 Example::
89
90   .mudpy.linguistic.actions:
91       ?: ask
92       ",": begin
93       -: begin
94       :: begin
95       ;: begin
96       "!": exclaim
97       ...: muse
98       .: say
99
100 .mudpy.linguistic.default_punctuation
101 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102
103 string, optional
104
105 Unpunctuated statements made by actors should be assumed to
106 terminate with this value.
107
108 Example::
109
110   .mudpy.linguistic.default_punctuation: .
111
112 .mudpy.linguistic.typos
113 ~~~~~~~~~~~~~~~~~~~~~~~
114
115 dict, optional
116
117 Replacements for common typographical and capitalization errors.
118
119 Example::
120
121   .mudpy.linguistic.typos:
122       i: I
123       i'd: I'd
124       i'll: I'll
125       i'm: I'm
126       teh: the
127       theyre: they're
128       youre: you're
129
130 .mudpy.limit
131 ------------
132
133 .mudpy.limit.admins
134 ~~~~~~~~~~~~~~~~~~~
135
136 list, optional
137
138 The first users to create accounts with names in this list will
139 automatically be given full administrative privileges.
140
141 Example::
142
143   .mudpy.limit.admins:
144       - admin
145
146 .mudpy.limit.avatars
147 ~~~~~~~~~~~~~~~~~~~~
148
149 int, required
150
151 This is the maximum number of avatars allowed for each account.
152
153 Example::
154
155   .mudpy.limit.avatars: 7
156
157 .mudpy.limit.backups
158 ~~~~~~~~~~~~~~~~~~~~
159
160 int, optional
161
162 This is the number of backups to keep and rotate when overwriting
163 data files. If unspecified or set to 0, no backup copies will be
164 made.
165
166 Example::
167
168   .mudpy.limit.backups: 10
169
170 .mudpy.limit.password_tries
171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
172
173 int, required
174
175 This is the maximum number of password failures allowed during the
176 login process. Once exceeded, the user will be disconnected.
177
178 Example::
179
180   .mudpy.limit.password_tries: 3
181
182 .mudpy.log
183 ----------
184
185 .mudpy.log.file
186 ~~~~~~~~~~~~~~~
187
188 string, optional
189
190 If set, log messages will be recorded to this file.
191
192 Example::
193
194   .mudpy.log.file: var/mudpy.log
195
196 .mudpy.log.lines
197 ~~~~~~~~~~~~~~~~
198
199 int, optional
200
201 Number of log entries to keep in memory (the oldest are
202 discarded)... If unset or 0, none will be written to mudpy's
203 internal memory.
204
205 Example::
206
207   .mudpy.log.lines: 1000
208
209 .mudpy.log.stdout
210 ~~~~~~~~~~~~~~~~~
211
212 bool, optional
213
214 If set to ``yes``, messages will be logged to the standard output of
215 the mudpy process. If unspecified, the default is ``no``.
216
217 Example::
218
219   .mudpy.log.stdout: true
220
221 .mudpy.log.syslog
222 ~~~~~~~~~~~~~~~~~
223
224 string, optional
225
226 If set, mudpy will send messages to the system log, and under the
227 name specified by this value (Unix derivatives only).
228
229 Example::
230
231   .mudpy.log.syslog: mudpy
232
233 .mudpy.movement
234 ---------------
235
236 .mudpy.movement.*.enter_term
237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
238
239 string, multiple
240
241 Word or words describing the direction from where you are seen to
242 enter the next room when moving.
243
244 Example::
245
246   .mudpy.movement.down.enter_term: above
247   .mudpy.movement.east.enter_term: the west
248   .mudpy.movement.north.enter_term: the south
249   .mudpy.movement.south.enter_term: the north
250   .mudpy.movement.up.enter_term: below
251   .mudpy.movement.west.enter_term: the east
252
253 .mudpy.movement.*.exit_term
254 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
255
256 string, multiple
257
258 Word or words describing the direction where you are seen to exit
259 the current room when moving.
260
261 Example::
262
263   .mudpy.movement.down.exit_term: downward
264   .mudpy.movement.east.exit_term: to the east
265   .mudpy.movement.north.exit_term: to the north
266   .mudpy.movement.south.exit_term: to the south
267   .mudpy.movement.up.exit_term: upward
268   .mudpy.movement.west.exit_term: to the west
269
270 .mudpy.movement.*.vector
271 ~~~~~~~~~~~~~~~~~~~~~~~~
272
273 triplet, multiple
274
275 Vector of signed integer units for use in vector addition to derive
276 the destination coordinates from the current coordinates when moving
277 through a gridlink exit. The example coordinate system used is left
278 handed (east, north and up are positive, west, south and down are
279 negative) and three-dimensional with a tuple component order of
280 (longitude, latitude, altitude).
281
282 Example::
283
284   .mudpy.movement.down.vector: [0, 0, -1]
285   .mudpy.movement.east.vector: [1, 0, 0]
286   .mudpy.movement.north.vector: [0, 1, 0]
287   .mudpy.movement.south.vector: [0, -1, 0]
288   .mudpy.movement.up.vector: [0, 0, 1]
289   .mudpy.movement.west.vector: [-1, 0, 0]
290
291 .mudpy.network
292 --------------
293
294 .mudpy.network.host
295 ~~~~~~~~~~~~~~~~~~~
296
297 string, optional
298
299 The IP address on which to listen. If unspecified, the default is
300 all available addresses.
301
302 Example::
303
304   .mudpy.network.host: ::1
305
306 .mudpy.network.port
307 ~~~~~~~~~~~~~~~~~~~
308
309 int, required
310
311 The TCP port on which to listen.
312
313 Example::
314
315   .mudpy.network.port: 4000
316
317 .mudpy.process
318 --------------
319
320 .mudpy.process.daemon
321 ~~~~~~~~~~~~~~~~~~~~~
322
323 bool, optional
324
325 If set to ``yes``, mudpy will immediately fork and detach a child to
326 become a daemon process, then close all open file descriptors and
327 terminate the parent process (Unix derivatives only). The default
328 value is ``no``.
329
330 Example::
331
332   .mudpy.process.daemon: true
333
334 .mudpy.process.pidfile
335 ~~~~~~~~~~~~~~~~~~~~~~
336
337 string, optional
338
339 If set, this filename will contain the daemon's process ID (Unix
340 derivatives only).
341
342 Example::
343
344   .mudpy.process.pidfile: var/mudpy.pid
345
346 .mudpy.timing
347 -------------
348
349 .mudpy.timing.idle.disconnect.*
350 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351
352 int, multiple
353
354 This value indicates the number of increments allowed to pass
355 without input on a socket connection before it is terminated. This
356 avoids accumulation of dead sockets which could otherwise max out
357 allowed file descriptors. The differentiators are either ``default``
358 or a state name used to override the default value for that specific
359 state (``active``, ``entering_account_name``, et cetera).
360
361 Example::
362
363   .mudpy.timing.idle.disconnect.active: 6048000
364   .mudpy.timing.idle.disconnect.default: 6000
365   .mudpy.timing.idle.disconnect.entering_account_name: 600
366
367 .mudpy.timing.idle.warn.*
368 ~~~~~~~~~~~~~~~~~~~~~~~~~
369
370 int, multiple
371
372 This value indicates the number of increments allowed to pass
373 without input on a socket connection before it is warned that
374 termination is imminent. The differentiators are either
375 ``default`` or a state name used to override the default value
376 for that specific state. It is recommended that this be less than
377 the corresponding ``.mudpy.timing.idle.disconnect.*`` value.
378
379 Example::
380
381   .mudpy.timing.idle.warn.active: 5040000
382   .mudpy.timing.idle.warn.default: 5000
383   .mudpy.timing.idle.warn.entering_account_name: 500
384
385 .mudpy.timing.increment
386 ~~~~~~~~~~~~~~~~~~~~~~~
387
388 float, required
389
390 This value indicates the number of real system clock seconds (or
391 more commonly, fraction thereof) each pass through the main loop is
392 intended to take. This roughly sets the frequency with which queued
393 socket I/O operations are performed, pending events are triggered,
394 and directly impacts the speed at which virtual time passes within
395 the simulation.
396
397 Example::
398
399   .mudpy.timing.increment: 0.1
400
401 .mudpy.timing.save
402 ~~~~~~~~~~~~~~~~~~
403
404 int, required
405
406 Number of increments between updates of changed persistent data
407 storage.
408
409 Example::
410
411   .mudpy.timing.save: 600
412
413 .mudpy.timing.status
414 ~~~~~~~~~~~~~~~~~~~~
415
416 int, optional
417
418 Number of increments to wait between logging mudpy status messages.
419 If unspecified or set to 0, no mudpy status messages will be
420 written.
421
422 Example::
423
424   .mudpy.timing.status: 6000