Skip to the content.

A Pythelix game is configured by one file: settings.txt, at the root of your game, next to the worldlets directory. It is a plain text file, meant to be opened and edited in Notepad or any other editor.

Pythelix generates it the first time it starts (the server, check or scenario all do), with every setting present, its default value and a comment saying what it does. You never need to write it from scratch.

What goes in it

The settings file only holds what the engine needs before it reads your worldlets: where the files are, which ports to listen on, how files and players are encoded, and the keys of the generic entities. Everything about how the game behaves belongs in a worldlet, where you have methods and inheritance.

The format

# A comment.
NAME=value

The file is read the same way worldlets are, so CRLF line endings, a byte-order mark or a Windows encoding won’t break it.

The settings

Setting Default What it does
DATABASE_PATH pythelix.db The SQLite database holding the game.
WORLDLETS_PATH worldlets The directory of worldlets.
PLUGINS_PATH plugins The directory of installed plugins.
PLUGIN_INDEX_URL the central registry Where bin/plugin finds the list of published plugins. Only an environment variable or a line you add yourself: most games never need it.
SCENARIOS_PATH scenarios The directory of scenarios.
TASKS_PATH tasks Where persistent tasks are stored.
TELNET_PORT 4000 The port players connect to with a MUD client.
WEB_PORT 8000 The port the web server listens on.
DEFAULT_ENCODING utf-8 The encoding a player’s client is assumed to use when it connects.
WORLDLETS_ENCODING (empty) How a worldlet or scenario file is read when it isn’t valid UTF-8 (see below). Empty means “the same as DEFAULT_ENCODING”.
GENERIC_CLIENT generic/client The key of the entity every client inherits from.
GENERIC_CHARACTER generic/character The key of the entity every character inherits from.
GENERIC_MENU generic/menu The key of the entity every menu inherits from.
GENERIC_COMMAND generic/command The key of the entity every command inherits from.
GENERIC_RANGEN generic/rangen The key of the entity every random-string generator inherits from.
GENERIC_CALENDAR generic/calendar The key of the entity every calendar inherits from.
SECRET_KEY_BASE (generated) The secret the web server signs its cookies with. Keep it private.

Supported encodings are utf-8, iso-8859-1, iso-8859-15 and cp1252. The server refuses to start if an encoding setting is anything else, and says so.

How worldlet files are read

Every worldlet and scenario file is tried as UTF-8 first. UTF-8 is strict about which bytes can follow which, so a file saved by an editor in a Windows encoding fails on its first accented character instead of being read as nonsense. Only then is the file decoded with WORLDLETS_ENCODING. The decision is made file by file, so one builder’s editor doesn’t have to agree with another’s.

When a file needed that fallback, apply and check say so:

worldlets\room.txt is not UTF-8 and was read as cp1252. Save it as UTF-8 so that it reads the same everywhere.
Worldlet applied from ...\worldlets: 34 entities were added or updated.

The worldlet works either way. The notice is there so you learn that your editor is saving in the wrong encoding, rather than discover it the day you move the files to another machine.

Running from source

When you run Pythelix from source with mix (in development or in the tests), settings.txt is not used: the values come from config/config.exs, and only the environment variables apply.