Evennia

https://www.evennia.com/docs/latest
Admin
Evennia is an open-source Python-based framework designed for creating online text-based multiplayer...
Tokens:2,015,499
Snippets:14,704
Trust Score:8.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Installation and Initialization Commands

Source: https://www.evennia.com/docs/latest/_sources/Setup/Installation-Git.md.txt

A sequence of terminal commands to clone the repository, set up the environment, and start the server.

```bash
cd to some place you want to do your development (like a folder
   /home/anna/muddev/ on Linux or a folder in your personal user directory on Windows).
git clone https://github.com/evennia/evennia.git  (a new folder evennia is created)
python3.11 -m venv evenv  (a new folder evenv is created)
source evenv/bin/activate (Linux, Mac), evenv\Scripts\activate (Windows)
pip install -e evennia
evennia --init mygame
cd mygame
evennia migrate
evennia start (make sure to make a  superuser when asked)
```

--------------------------------

### Add Grid Example

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-XYZGrid.html

Loads the provided example grid configuration.

```bash
$ evennia xyzgrid add evennia.contrib.grid.xyzgrid.example
```

--------------------------------

### Initialize database and start server

Source: https://www.evennia.com/docs/latest/Howtos/Tutorial-Using-Arxcode.html

Run database migrations and start the Evennia server.

```bash
evennia migrate
```

```bash
evennia start
```

--------------------------------

### Define EvMenu nodes and start the menu

Source: https://www.evennia.com/docs/latest/Components/EvMenu.html

This example demonstrates mapping node identifiers to Python functions and initializing an EvMenu instance.

```python
        ┌─
        │  def nodeA(caller, raw_string, **kwargs):
        │      text = "Choose how to operate on 2 and 3."
        │      options = (
        │          {
        │              "key": "A",
        │              "desc": "Multiply 2 with 3",
        │              "goto": (_callback, {"type": "mult", "a": 2, "b": 3})
        │          },                      ───────────────────┬────────────
        │          {                                          │
        │              "key": "B",                            └───────────────┐
        │              "desc": "Add 2 and 3",                                 │
  Node A│              "goto": (_callback, {"type": "add", "a": 2, "b": 3})   │
        │          },                      ─────────────────┬─────────────    │
        │          {                                        │                 │
        │              "key": "C",                          │                 │
        │              "desc": "Show the value 5",          │                 │
        │              "goto": ("node_B", {"c": 5})         │                 │
        │          }                      ───────┐          │                 │
        │      )                                 └──────────┼─────────────────┼───┐
        │      return text, options                         │                 │   │
        └─                                       ┌──────────┘                 │   │
                                                 │                            │   │
                                                 │ ┌──────────────────────────┘   │
        ┌─                                       ▼ ▼                              │
        │  def _callback(caller, raw_string, **kwargs):
        │      if kwargs["type"] == "mult":
        │          return "node_B", {"c": kwargs["a"] * kwargs["b"]}
Goto-   │                           ───────────────┬────────────────              │
callable│                                          │                              │
        │                                          └───────────────────┐          │
        │                                                              │          │
        │      elif kwargs["type"] == "add":                           │          │
        │          return "node_B", {"c": kwargs["a"] + kwargs["b"]}
        └─                          ────────┬───────────────────────   │          │
                                            │                          │          │
                                            │ ┌────────────────────────┼──────────┘
                                            │ │                        │
                                            │ │ ┌──────────────────────┘
        ┌─                                  ▼ ▼ ▼
        │  def nodeB(caller, raw_string, **kwargs):
  Node B│      text = "Result of operation: " + kwargs["c"]
        │      return text, {}
        └─

        ┌─
   Menu │  EvMenu(caller, {"node_A": nodeA, "node_B": nodeB}, startnode="node_A")
   Start│
        └─
```

--------------------------------

### Start Server

Source: https://www.evennia.com/docs/latest/Howtos/Tutorial-Using-Arxcode.html

Start the server using winpty to handle console input prompts.

```bash
winpty ../evennia/bin/windows/evennia.bat start
```

--------------------------------

### Starting Server Interactively

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/evennia_launcher.html

Starts the server in the foreground under control of the launcher process.

```python
def start_server_interactive():
    """
    Start the Server under control of the launcher process (foreground)

    """

    def _iserver():
        _, server_twistd_cmd = _get_twistd_cmdline(False, False)
        server_twistd_cmd.append("--nodaemon")
        print("Starting Server in interactive mode (stop with Ctrl-C)...")
        try:
            Popen(server_twistd_cmd, env=getenv(), stderr=STDOUT).wait()
        except KeyboardInterrupt:
            print("... Stopped Server with Ctrl-C.")
        else:
            print("... Server stopped (leaving interactive mode).")

    collectstatic()
    stop_server_only(when_stopped=_iserver, interactive=True)
```

--------------------------------

### Starting Portal Interactively

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/evennia_launcher.html

Starts the portal in the foreground, requiring the server to be started first.

```python
def start_portal_interactive():
    """
    Start the Portal under control of the launcher process (foreground)

    Notes:
        In a normal start, the launcher waits for the Portal to start, then
        tells it to start the Server. Since we can't do this here, we instead
        start the Server first and then starts the Portal - the Server will
        auto-reconnect to the Portal. To allow the Server to be reloaded, this
        relies on a fixed server server-cmdline stored as a fallback on the
        portal application in evennia/server/portal/portal.py.

    """

    def _iportal(fail):
        portal_twistd_cmd, server_twistd_cmd = _get_twistd_cmdline(False, False)
        portal_twistd_cmd.append("--nodaemon")
```

--------------------------------

### Install documentation dependencies

Source: https://www.evennia.com/docs/latest/Contributing-Docs.html

Commands to install the necessary requirements for building documentation.

```bash
make install
or
pip install -r requirements.txt
```

--------------------------------

### XYZGrid Command Usage Examples

Source: https://www.evennia.com/docs/latest/_modules/evennia/contrib/grid/xyzgrid/launchcmd.html

Various command-line examples for interacting with the XYZ grid system.

```bash
evennia xyzgrid list
evennia xyzgrid list mymap
evennia xyzgrid list "the small cave"
```

```bash
evennia xyzgrid init
```

```bash
evennia xyzgrid add evennia.contrib.grid.xyzgrid.example
evennia xyzgrid add world.mymap1 world.mymap2 world.mymap3
```

```bash
evennia xyzgrid spawn                  - spawn all
evennia xyzgrid "(*, *, mymap1)"       - spawn everything of map/zcoord mymap1
evennia xyzgrid "(12, 5, mymap1)"      - spawn only coordinate (12, 5) on map/zcoord mymap1
```

```bash
evennia xyzgrid initpath
evennia xyzgrid initpath mymap1
evennia xyzgrid initpath "the small cave"
```

--------------------------------

### Start Evennia server

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/evennia_launcher.html

Launches the Evennia Portal, which subsequently starts the Server component.

```python
def start_evennia(pprofiler=False, sprofiler=False):
    """
    This will start Evennia anew by launching the Evennia Portal (which in turn
    will start the Server)

    """
    portal_cmd, server_cmd = _get_twistd_cmdline(pprofiler, sprofiler)

    def _fail(fail):
        print(fail)
        _reactor_stop()

    def _server_started(response):
        print("... Server started.\nEvennia running.")
        if response:
            _, _, _, _, pinfo, sinfo = response
            _print_info(pinfo, sinfo)
        _reactor_stop()

    def _portal_started(*args):
        print(
            "... Portal started.\nServer starting {} ...".format(
                "(under cProfile)" if sprofiler else ""
            )
        )
        wait_for_status_reply(_server_started)
        send_instruction(SSTART, server_cmd)

    def _portal_running(response):
        prun, srun, ppid, spid, _, _ = _parse_status(response)
        print("Portal is already running as process {pid}. Not restarted.".format(pid=ppid))
        if srun:
            print("Server is already running as process {pid}. Not restarted.".format(pid=spid))
            _reactor_stop()
        else:
            print("Server starting {}...".format("(under cProfile)" if sprofiler else ""))
            send_instruction(SSTART, server_cmd, _server_started, _fail)

    def _portal_not_running(fail):
        print("Portal starting {}...".format("(under cProfile)" if pprofiler else ""))
        try:
            if _is_windows():
                # Windows requires special care
                create_no_window = 0x08000000
                Popen(portal_cmd, env=getenv(), bufsize=-1, creationflags=create_no_window)
            else:
                Popen(portal_cmd, env=getenv(), bufsize=-1)
        except Exception as e:
            print(PROCESS_ERROR.format(component="Portal", traceback=e))
            _reactor_stop()
        wait_for_status(True, None, _portal_started)

    collectstatic()
    send_instruction(PSTATUS, None, _portal_running, _portal_not_running)
```

--------------------------------

### Crafting Command Examples

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-Crafting.html

Practical examples of using the craft command and defining recipe logic.

```text
craft toy car from plank, wooden wheels, nails using saw, hammer
```

```text
snow + snowball_recipe -> snowball
```

```text
spell_book + wand + fireball_recipe -> fireball
```

```text
stick + string + hook -> makeshift_fishing_rod
makeshift_fishing_rod + storm_drain -> key
```

--------------------------------

### start(key)

Source: https://www.evennia.com/docs/latest/_modules/evennia/scripts/scripthandler.html

Finds scripts on the object by key or dbref and forces them to start.

```APIDOC
### Method
`start(key)`

### Description
Searches for scripts on the current object matching the provided key or dbref and triggers their start method.

### Parameters
- **key** (str) - Required - The script's key or dbref.

### Returns
- **int** - The number of scripts that were successfully started.
```

--------------------------------

### Handle Setup Sequence

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/initial_setup.html

Manages the execution flow of the setup sequence, allowing for resumption if a step fails.

```python
def handle_setup(last_step=None):
    """
    Main logic for the module. It allows for restarting the
    initialization at any point if one of the modules should crash.

    Args:
        last_step (str, None): The last stored successful step, for starting
            over on errors. None if starting from scratch. If this is 'done',
            the function will exit immediately.

    """
    # setup sequence
    setup_sequence = {
        "create_objects": create_objects,
        "at_initial_setup": at_initial_setup,
        "collectstatic": collectstatic,
        "done": reset_server,
    }

    if last_step in ("done", -1):
        # this means we don't need to handle setup since
        # it already ran sucessfully once. -1 is the legacy
        # value for existing databases.
        return

    # determine the sequence so we can skip ahead
    steps = list(setup_sequence)
    steps = steps[steps.index(last_step) + 1 if last_step is not None else 0 :]

    # step through queue from last completed function. Once completed,
    # the 'done' key should be set.
    for stepname in steps:
        try:
            setup_sequence[stepname]()
        except Exception:
            # we re-raise to make sure to stop startup
            raise
        else:
            # save the step
            ServerConfig.objects.conf("last_initial_setup_step", stepname)
            if stepname == "done":
                # always exit on 'done'
                break
```

--------------------------------

### evennia.utils.gametime.gametime(absolute=False)

Source: https://www.evennia.com/docs/latest/api/evennia.utils.gametime.html

Get the total gametime of the server since first start.

```APIDOC
## gametime(absolute=False)

### Description
Returns the total gametime of the server as a virtual timestamp.

### Parameters
- **absolute** (bool, optional) - If True, returns the absolute game time including the epoch, suitable for conversion to an in-game date.
```

--------------------------------

### Get task time-delta

Source: https://www.evennia.com/docs/latest/_modules/evennia/scripts/ondemandhandler.html

Calculates the time elapsed since the task started.

```python
def get_dt(self, key, category=None, **kwargs):
    """
    Get the time-delta since the task started.

    Args:
        key (str, callable, OnDemandTask or Object): The unique identifier for the task. If a
            callable, will be called without arguments. If an Object, will be converted to a
            string.  If an `OnDemandTask`, then all other arguments are ignored and the task
            will be used to identify the task to get the time-delta from.
        **kwargs: Will be passed to the stage function, if one is called.

    Returns:
        int or None: The time since the last check, or `None` if no task was found.

    """
    task = self.get(key, category)
    return task.get_dt(**kwargs) if task else None
```

--------------------------------

### Command Parsing Examples

Source: https://www.evennia.com/docs/latest/_modules/evennia/contrib/grid/xyzgrid/commands.html

Example syntax for opening exits to specific locations or coordinates.

```text
open kitchen = Kitchen
open north, south = Town Center
open cave mouth;cave = (3, 4, the small cave)
```

--------------------------------

### Virtualenv creation error

Source: https://www.evennia.com/docs/latest/Setup/Installation-Troubleshooting.html

Example of the error message encountered when virtualenv setup fails.

```text
Error: Command '['evenv', '-Im', 'ensurepip', '--upgrade', '--default-pip']'
returned non-zero exit status 1
```

--------------------------------

### Build the Tutorial World

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-Tutorial-World.html

Execute this command as a superuser to generate the tutorial world and connect it to Limbo.

```text
batchcommand contrib.tutorials.tutorial_world.build
```

--------------------------------

### evennia.utils.gametime.runtime(format=False)

Source: https://www.evennia.com/docs/latest/api/evennia.utils.gametime.html

Get the total runtime of the server since first start, excluding downtimes.

```APIDOC
## runtime(format=False)

### Description
Returns the total runtime of the server since its first start, excluding any downtime periods.

### Parameters
- **format** (bool, optional) - If True, returns the time split into time units instead of a float.
```

--------------------------------

### Install system prerequisites

Source: https://www.evennia.com/docs/latest/Setup/Installation-Android.html

Install necessary libraries and compilers required for Evennia dependencies like Pillow and Twisted.

```bash
$ pkg install -y clang git zlib ndk-sysroot libjpeg-turbo libcrypt python
```

--------------------------------

### Run initial setup

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/service.html

Triggers the initial setup script upon portal connection, handling first-time population or resuming interrupted steps.

```python
[docs]
    def run_initial_setup(self):
        """
        This is triggered by the amp protocol when the connection
        to the portal has been established.
        This attempts to run the initial_setup script of the server.
        It returns if this is not the first time the server starts.
        Once finished the last_initial_setup_step is set to 'done'

        """

        initial_setup = importlib.import_module(settings.INITIAL_SETUP_MODULE)
        last_initial_setup_step = evennia.ServerConfig.objects.conf("last_initial_setup_step")
        try:
            if not last_initial_setup_step:
                # None is only returned if the config does not exist,
                # i.e. this is an empty DB that needs populating.
                self.info_dict["info"] = " Server started for the first time. Setting defaults."
                initial_setup.handle_setup()
            elif last_initial_setup_step not in ("done", -1):
                # last step crashed, so we weill resume from this step.
                # modules and setup will resume from this step, retrying
                # the last failed module. When all are finished, the step
                # is set to 'done' to show it does not need to be run again.
                self.info_dict["info"] = " Resuming initial setup from step '{last}'.".format(
                    last=last_initial_setup_step
                )
                initial_setup.handle_setup(last_initial_setup_step)
        except Exception:
            # stop server if this happens.
            print(traceback.format_exc())
            if not settings.TEST_ENVIRONMENT or not evennia.SESSION_HANDLER:
                print("Error in initial setup. Stopping Server + Portal.")
                evennia.SESSION_HANDLER.portal_shutdown()
```

--------------------------------

### Example Command Usage

Source: https://www.evennia.com/docs/latest/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Building-Quickstart.html

Demonstrates creating an object with a drop switch.

```text
 create/drop box
```

--------------------------------

### Start a bot session

Source: https://www.evennia.com/docs/latest/api/evennia.server.sessionhandler.html

Example usage of the start_bot_session method to initiate a bot connection via the Portal.

```python
start_bot_session("evennia.server.portal.irc.IRCClient",
     
{"uid":1, "botname":"evbot", "channel":"#evennia",
    
"network:"irc.freenode.net", "port": 6667})
```

--------------------------------

### Example Callback Code

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-Ingame-Python.html

A simple callback script triggered by the 'get' event to send a message to the character.

```python
character.msg("You have picked up {} and have completed this quest!".format(obj.get_display_name(character)))
```

--------------------------------

### Initialize the database

Source: https://www.evennia.com/docs/latest/Contributing-Docs.html

Run migrations to set up an empty database for the documentation build process.

```bash
evennia migrate
```

--------------------------------

### EvenniaTestMixin Setup Methods

Source: https://www.evennia.com/docs/latest/_modules/evennia/utils/test_resources.html

Methods for initializing and cleaning up accounts, rooms, objects, characters, and sessions in test environments.

```python
class EvenniaTestMixin:
    """
    Evennia test environment mixin
    """

    account_typeclass = DefaultAccount
    object_typeclass = DefaultObject
    character_typeclass = DefaultCharacter
    exit_typeclass = DefaultExit
    room_typeclass = DefaultRoom
    script_typeclass = DefaultScript

    def create_accounts(self):
        self.account = create.create_account(
            "TestAccount",
            email="test@test.com",
            password="testpassword",
            typeclass=self.account_typeclass,
        )
        self.account2 = create.create_account(
            "TestAccount2",
            email="test@test.com",
            password="testpassword",
            typeclass=self.account_typeclass,
        )
        self.account.permissions.add("Developer")

    def teardown_accounts(self):
        if hasattr(self, "account"):
            self.account.delete()
        if hasattr(self, "account2"):
            self.account2.delete()

    # Set up fake prototype module for allowing tests to use named prototypes.
    @override_settings(PROTOTYPE_MODULES=["evennia.utils.tests.data.prototypes_example"])
    def create_rooms(self):
        self.room1 = create.create_object(self.room_typeclass, key="Room", nohome=True)
        self.room1.db.desc = "room_desc"

        self.room2 = create.create_object(self.room_typeclass, key="Room2")
        self.exit = create.create_object(
            self.exit_typeclass, key="out", location=self.room1, destination=self.room2
        )

    def create_objs(self):
        self.obj1 = create.create_object(
            self.object_typeclass, key="Obj", location=self.room1, home=self.room1
        )
        self.obj2 = create.create_object(
            self.object_typeclass, key="Obj2", location=self.room1, home=self.room1
        )

    def create_chars(self):
        self.char1 = create.create_object(
            self.character_typeclass, key="Char", location=self.room1, home=self.room1
        )
        self.char1.permissions.add("Developer")
        self.char2 = create.create_object(
            self.character_typeclass, key="Char2", location=self.room1, home=self.room1
        )
        self.char1.account = self.account
        self.account.db._last_puppet = self.char1
        self.char2.account = self.account2
        self.account2.db._last_puppet = self.char2

    def create_script(self):
        self.script = create.create_script(self.script_typeclass, key="Script")

    def setup_session(self):
        dummysession = ServerSession()
        dummysession.init_session("telnet", ("localhost", "testmode"), evennia.SESSION_HANDLER)
        dummysession.sessid = 1
        evennia.SESSION_HANDLER.portal_connect(
            dummysession.get_sync_data()
        )  # note that this creates a new Session!
        session = evennia.SESSION_HANDLER.session_from_sessid(1)  # the real session
        evennia.SESSION_HANDLER.login(session, self.account, testmode=True)
        self.session = session

    def teardown_session(self):
        if hasattr(self, "sessions"):
            del evennia.SESSION_HANDLER[self.session.sessid]
```

--------------------------------

### Get Backup Server Command

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/portal/service.html

Generates the command line instruction for starting the server in interactive Portal mode.

```python
def _get_backup_server_twistd_cmd(self):
    """
    For interactive Portal mode there is no way to get the server cmdline from the launcher, so
    we need to guess it here (it's very likely to not change)

    Returns:
        server_twistd_cmd (list): An instruction for starting the server, to pass to Popen.

    """
    server_twistd_cmd = [
        "twistd",
        "--python={}".format(os.path.join(dirname(dirname(abspath(__file__))), "server.py")),
    ]
    if os.name != "nt":
        gamedir = os.getcwd()
        server_twistd_cmd.append(
            "--pidfile={}".format(os.path.join(gamedir, "server", "server.pid"))
        )
    return server_twistd_cmd
```

--------------------------------

### start_all_dummy_clients(nclients)

Source: https://www.evennia.com/docs/latest/api/evennia.server.profiling.dummyrunner.html

Initializes a specified number of dummy clients, connects them to the server, and begins their execution steps.

```APIDOC
## start_all_dummy_clients(nclients)

### Description
Initializes all dummy clients, connects them to the server, and starts the stepping process for each.

### Parameters
- **nclients** (int) - Required - The number of dummy clients to connect.
```

--------------------------------

### Interact with the building menu

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-Building-Menu.html

Example session showing the menu output after initialization.

```text
> @edit here
Building menu: A beautiful meadow

 [T]itle: A beautiful meadow
 [D]escription:
   This is a beautiful meadow.  But so beautiful I can't describe it.
 [E]xits:
  north
  south
 [Q]uit the menu

> q
Closing the editor.
```

--------------------------------

### Configure Server Initialization and Login Delay

Source: https://www.evennia.com/docs/latest/_sources/Setup/Settings-Default.md.txt

Sets the login start delay and specifies modules for initial database setup and custom hooks.

```python
DELAY_CMD_LOGINSTART = 0.3
INITIAL_SETUP_MODULE = "evennia.server.initial_setup"
AT_INITIAL_SETUP_HOOK_MODULE = "server.conf.at_initial_setup"
```

--------------------------------

### Initialize and spawn an XYZGrid example

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-XYZGrid.html

Commands to initialize the XYZGrid system, add an example map, and spawn the grid into the game world.

```bash
evennia xyzgrid init
evennia xyzgrid add evennia.contrib.grid.xyzgrid.example
evennia xyzgrid list
evennia xyzgrid show "the large tree"
evennia xyzgrid show "the small cave"
evennia xyzgrid spawn
evennia reload
```

--------------------------------

### Get numbered object names

Source: https://www.evennia.com/docs/latest/_modules/evennia/objects/objects.html

Examples of how to retrieve singular and plural forms of an object's name based on count and formatting options.

```python
obj.get_numbered_name(3, looker, key="foo")
      -> ("a foo", "three foos")
obj.get_numbered_name(1, looker, key="Foobert", return_string=True)
      -> "a Foobert"
obj.get_numbered_name(1, looker, key="Foobert", return_string=True, no_article=True)
      -> "Foobert"
```

--------------------------------

### Create TutorialMirror

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-Mirror.html

Command to instantiate the TutorialMirror object within the game world.

```text
create/drop mirror:contrib.tutorials.mirror.TutorialMirror
```

--------------------------------

### Test Crafting Sword Setup

Source: https://www.evennia.com/docs/latest/_modules/evennia/contrib/game_systems/crafting/tests.html

Initializes the test environment for crafting an example sword, including mocking the crafter and defining helper functions for object creation.

```python
class TestCraftSword(BaseEvenniaTestCase):
    """
    Test the `craft` function by crafting the example sword.

    """

    def setUp(self):
        self.crafter = mock.MagicMock()
        self.crafter.msg = mock.MagicMock()

    @override_settings(CRAFT_RECIPE_MODULES=[], DEFAULT_HOME="#999999")
    @mock.patch("evennia.contrib.game_systems.crafting.example_recipes.random")
    def test_craft_sword(self, mockrandom):
        """
        Craft example sword. For the test, every crafting works.

        """
        # make sure every craft succeeds
        mockrandom.random = mock.MagicMock(return_value=0.2)

        def _co(key, tagkey, is_tool=False):
            tagcat = "crafting_tool" if is_tool else "crafting_material"
            return create_object(key=key, tags=[(tagkey, tagcat)], nohome=True)

        def _craft(recipe_name, *inputs):
            """shortcut to shorten and return only one element"""
            result = crafting.craft(self.crafter, recipe_name, *inputs, raise_exception=True)
            return result[0] if len(result) == 1 else result

        # generate base materials
        iron_ore1 = _co("Iron ore ingot", "iron ore")
        iron_ore2 = _co("Iron ore ingot", "iron ore")
        iron_ore3 = _co("Iron ore ingot", "iron ore")

        ash1 = _co("Pile of Ash", "ash")
        ash2 = _co("Pile of Ash", "ash")
        ash3 = _co("Pile of Ash", "ash")
```

--------------------------------

### Execute Initial Setup Hook

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/initial_setup.html

Dynamically imports and executes the 'at_initial_setup' function from the module defined in settings.

```python
modname = settings.AT_INITIAL_SETUP_HOOK_MODULE
    if not modname:
        return
    try:
        mod = __import__(modname, fromlist=[None])
    except (ImportError, ValueError):
        return
    logger.log_info("Initial setup: Running at_initial_setup() hook.")
    if mod.__dict__.get("at_initial_setup", None):
        mod.at_initial_setup()
```

--------------------------------

### Install Evennia (macOS)

Source: https://www.evennia.com/docs/latest/Setup/Installation-Git.html

Updates pip and setuptools before installing Evennia in editable mode to avoid common macOS installation issues.

```bash
pip install --upgrade pip   # Old pip versions may be an issue on Mac.
pip install --upgrade setuptools   # Ditto concerning Mac issues.
pip install -e evennia
```

--------------------------------

### Install Arxcode Dependencies

Source: https://www.evennia.com/docs/latest/Howtos/Tutorial-Using-Arxcode.html

Install the required dependencies for Arxcode.

```bash
cd ../arxcode
pip install -r requirements.txt
```

--------------------------------

### Create a TutorialMirror object

Source: https://www.evennia.com/docs/latest/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Python-basic-introduction.html

Use the create command to instantiate a mirror object from the Evennia contrib library.

```text
> create/drop mirror:contrib.tutorials.mirror.TutorialMirror
```

--------------------------------

### NAttributeProperty usage example

Source: https://www.evennia.com/docs/latest/_modules/evennia/typeclasses/attributes.html

Example of defining an NAttributeProperty on a class.

```python
class NAttributeProperty(AttributeProperty):
    """
    NAttribute property descriptor. Allows for specifying NAttributes as Django-like 'fields'
    on the class level.

    Example:
    ::

        class Character(DefaultCharacter):
            foo = NAttributeProperty(default="Bar")

    """

    attrhandler_name = "nattributes"
```

--------------------------------

### Start Evennia with cProfile

Source: https://www.evennia.com/docs/latest/Coding/Profiling.html

Use the launcher to initiate the server process under the cProfile profiler.

```bash
evennia --profiler start
```

--------------------------------

### Example Output Message

Source: https://www.evennia.com/docs/latest/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Making-A-Sittable-Object.html

Example of a custom sitting message.

```text
You sit down and a whoopie cushion makes a loud fart noise!
```

--------------------------------

### Start Dummy Clients

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/profiling/dummyrunner.html

Initializes and connects the specified number of dummy clients.

```python
def start_all_dummy_clients(nclients):
    """
    Initialize all clients, connect them and start to step them

    Args:
        nclients (int): Number of dummy clients to connect.

    """
    global NCLIENTS
    NCLIENTS = int(nclients)
    actions = DUMMYRUNNER_SETTINGS.ACTIONS

    if len(actions) < 2:
        print(ERROR_FEW_ACTIONS)
        return
```

--------------------------------

### Script Initialization and Property Setup

Source: https://www.evennia.com/docs/latest/_modules/evennia/scripts/scripts.html

Handles the initialization of script properties and applies creation dictionary overrides if provided.

```python
        self.basetype_setup()
        self.at_script_creation()
        # initialize Attribute/TagProperties
        self.init_evennia_properties()

        if hasattr(self, "_createdict"):
            # this will only be set if the utils.create_script
            # function was used to create the object. We want
            # the create call's kwargs to override the values
            # set by hooks.
            cdict = self._createdict
            updates = []
            if not cdict.get("key"):
                if not self.db_key:
                    if hasattr(self, "key"):
                        # take key from the object typeclass
                        self.db_key = self.key
                    else:
                        # no key set anywhere, use class+dbid as key
                        self.db_key = f"{self.__class__.__name__}(#{self.dbid})"
                    updates.append("db_key")
            elif self.db_key != cdict["key"]:
                self.db_key = cdict["key"]
                updates.append("db_key")
            if cdict.get("interval") and self.interval != cdict["interval"]:
                self.db_interval = max(0, cdict["interval"])
                updates.append("db_interval")
            if cdict.get("start_delay") and self.start_delay != cdict["start_delay"]:
                self.db_start_delay = cdict["start_delay"]
                updates.append("db_start_delay")
            if cdict.get("repeats") and self.repeats != cdict["repeats"]:
                self.db_repeats = max(0, cdict["repeats"])
                updates.append("db_repeats")
            if cdict.get("persistent") and self.persistent != cdict["persistent"]:
                self.db_persistent = cdict["persistent"]
                updates.append("db_persistent")
            if cdict.get("desc") and self.desc != cdict["desc"]:
                self.db_desc = cdict["desc"]
                updates.append("db_desc")
            if updates:
                self.save(update_fields=updates)

            if cdict.get("permissions"):
                self.permissions.batch_add(*cdict["permissions"])
            if cdict.get("locks"):
                self.locks.add(cdict["locks"])
            if cdict.get("tags"):
                # this should be a list of tags, tuples (key, category) or (key, category, data)
                self.tags.batch_add(*cdict["tags"])
            if cdict.get("attributes"):
                # this should be tuples (key, val, ...)
                self.attributes.batch_add(*cdict["attributes"])
            if cdict.get("nattributes"):
                # this should be a dict of nattrname:value
                for key, value in cdict["nattributes"]:
                    self.nattributes.add(key, value)

            if cdict.get("autostart"):
                # autostart the script
                self._start_task(force_restart=True)
```

--------------------------------

### Start Turn Logic

Source: https://www.evennia.com/docs/latest/_modules/evennia/contrib/game_systems/turnbattle/tb_range.html

Replenishes character actions at the start of their turn.

```python
    def start_turn(self, character):
        """
        Readies a character for the start of their turn by replenishing their
        available actions and notifying them that their turn has come up.

        Args:
            character (obj): Character to be readied.

        Notes:
            In this example, characters are given two actions per turn. This allows
            characters to both move and attack in the same turn (or, alternately,
            move twice or attack twice).
        """
        super().start_turn(character)
        character.db.combat_actionsleft = ACTIONS_PER_TURN
```

--------------------------------

### Start the Evennia server

Source: https://www.evennia.com/docs/latest/Howtos/Web-Add-a-wiki.html

Restart the server to initialize the wiki.

```bash
evennia start
```

--------------------------------

### Install Certbot

Source: https://www.evennia.com/docs/latest/Setup/Config-HAProxy.html

Install the Certbot utility on Debian or Ubuntu systems.

```bash
sudo apt install certbot
```

--------------------------------

### Install Django-wiki via pip

Source: https://www.evennia.com/docs/latest/Howtos/Web-Add-a-wiki.html

Install the wiki package and its dependencies.

```bash
pip install wiki
```

--------------------------------

### Example Batch Command File

Source: https://www.evennia.com/docs/latest/Components/Batch-Command-Processor.html

A sample .ev file demonstrating object creation, description setting with multi-line text, and file insertion.

```text
    #
    # This is an example batch build file for Evennia. 
    #
    
    # This creates a red button
    @create button:tutorial_examples.red_button.RedButton
    # (This comment ends input for @create)
    # Next command. Let's create something. 
    @set button/desc = 
      This is a large red button. Now and then 
      it flashes in an evil, yet strangely tantalizing way. 
    
      A big sign sits next to it. It says:

    
    -----------
    
     Press me! 
    
    -----------

    
      ... It really begs to be pressed! You 
    know you want to! 
    
    # This inserts the commands from another batch-cmd file named
    # batch_insert_file.ev.
    #INSERT examples.batch_insert_file
    
      
    # (This ends the @set command). Note that single line breaks 
    # and extra whitespace in the argument are ignored. Empty lines 
    # translate into line breaks in the output.
    # Now let's place the button where it belongs (let's say limbo #2 is 
    # the evil lair in our example)
    @teleport #2
    # (This comments ends the @teleport command.) 
    # Now we drop it so others can see it. 
    # The very last command in the file needs not be ended with #.
    drop button
```

--------------------------------

### Initialize account properties

Source: https://www.evennia.com/docs/latest/_modules/evennia/accounts/accounts.html

Sets up basic security and command sets for a new account.

```python
def basetype_setup(self):
        """
        This sets up the basic properties for an account. Overload this
        with at_account_creation rather than changing this method.

        """
        # A basic security setup
        self.locks.add(self.lockstring)

        # The ooc account cmdset
        self.cmdset.add_default(_CMDSET_ACCOUNT, persistent=True)
```

--------------------------------

### Model Naming Examples

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-Llm.html

Specific examples of quantized model identifiers.

```text
TheBloke/Llama-2-7B-Chat-GGML
TheBloke/StableBeluga-13B-GPTQ
```

--------------------------------

### Initialize and Build XYZgrid

Source: https://www.evennia.com/docs/latest/api/evennia.contrib.grid.xyzgrid.example.html

Commands to initialize, add examples, and build the grid using the Evennia command line interface.

```bash
evennia xyzgrid init
evennia xyzgrid add evennia.contrib.grid.xyzgrid.map_example
evennia xyzgrid build
```

--------------------------------

### Cooperate Task Start

Source: https://www.evennia.com/docs/latest/_modules/twisted/internet/task.html

Starts running an iterator as a long-running cooperative task.

```python
    def cooperate(self, iterator: Iterator[_TaskResultT]) -> CooperativeTask:
        """
        Start running the given iterator as a long-running cooperative task, by
        calling next() on it as a periodic timed event.

        @param iterator: the iterator to invoke.

```

--------------------------------

### Start HAProxy

Source: https://www.evennia.com/docs/latest/Setup/Config-HAProxy.html

Launch the HAProxy process using the specified configuration file.

```bash
sudo haproxy -f /path/to/the/above/haproxy.cfg
```

--------------------------------

### Initialize TutorialWeaponRack

Source: https://www.evennia.com/docs/latest/_modules/evennia/contrib/tutorials/tutorial_world/objects.html

The at_object_creation method sets up the default command set and initial database attributes for the rack.

```python
    def at_object_creation(self):
        """
        called at creation
        """
        self.cmdset.add_default(CmdSetWeaponRack, persistent=True)
        self.db.rack_id = "weaponrack_1"
        # these are prototype names from the prototype
        # dictionary above.
        self.db.get_weapon_msg = dedent(
            """
            You find |c%s|n. While carrying this weapon, these actions are available:
              |wstab/thrust/pierce <target>|n - poke at the enemy. More damage but harder to hit.
              |wslash/chop/bash <target>|n - swipe at the enemy. Less damage but easier to hit.
              |wdefend/parry|n - protect yourself and make yourself harder to hit.)
            """
        ).strip()

        self.db.no_more_weapons_msg = "you find nothing else of use."
        self.db.available_weapons = ["knife", "dagger", "sword", "club"]
```

--------------------------------

### Starting Server Only

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/evennia_launcher.html

Tells the portal to start the server, typically for debugging purposes.

```python
def start_only_server():
    """
    Tell portal to start server (debug)
    """
    portal_cmd, server_cmd = _get_twistd_cmdline(False, False)
    print("launcher: Sending to portal: SSTART + {}".format(server_cmd))
    collectstatic()
    send_instruction(SSTART, server_cmd)
```

--------------------------------

### Initialize a new Evennia application

Source: https://www.evennia.com/docs/latest/Concepts/Models.html

Create a new application subsystem and move it into the project's world directory.

```bash
 evennia startapp myapp
 mv myapp world  (linux)
 move myapp world   (windows)

```

--------------------------------

### Initialize Web Proxy Service

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/portal/service.html

Configures and starts the web proxy service, including plugin loading and interface binding.

```python
try:
    WEB_PLUGINS_MODULE = mod_import(settings.WEB_PLUGINS_MODULE)
except ImportError:
    WEB_PLUGINS_MODULE = None
    self.info_dict["errors"] = (
        "WARNING: settings.WEB_PLUGINS_MODULE not found - "
        "copy 'evennia/game_template/server/conf/web_plugins.py to "
        "mygame/server/conf."
    )

if WEB_PLUGINS_MODULE:
    try:
        web_root = WEB_PLUGINS_MODULE.at_webproxy_root_creation(web_root)
    except Exception:
        # Legacy user has not added an at_webproxy_root_creation function in existing
        # web plugins file
        self.info_dict["errors"] = (
            "WARNING: WEB_PLUGINS_MODULE is enabled but at_webproxy_root_creation() "
            "not found copy 'evennia/game_template/server/conf/web_plugins.py to "
            "mygame/server/conf."
        )
web_root = Website(web_root, logPath=settings.HTTP_LOG_FILE)
web_root.is_portal = True
proxy_service = internet.TCPServer(proxyport, web_root, interface=interface)
proxy_service.setName("EvenniaWebProxy%s:%s" % (ifacestr, proxyport))
proxy_service.setServiceParent(self)
self.info_dict["webserver_proxy"].append(
    "webserver-proxy%s: %s" % (ifacestr, proxyport)
)
self.info_dict["webserver_internal"].append("webserver: %s" % serverport)
```

--------------------------------

### Install UFW Firewall

Source: https://www.evennia.com/docs/latest/Setup/Security-Practices.html

Installs the Uncomplicated Firewall utility on Ubuntu systems.

```bash
# Install ufw (if not already)
sudo apt-get install ufw
```

--------------------------------

### Execute custom initial setup hook

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/initial_setup.html

Provides a hook for users to run custom logic at the end of the initial setup sequence.

```python
def at_initial_setup():
    """
    Custom hook for users to overload some or all parts of the initial
    setup. Called very last in the sequence. It tries to import and
    srun a module settings.AT_INITIAL_SETUP_HOOK_MODULE and will fail
    silently if this does not exist or fails to load.
```

--------------------------------

### Install Evennia

Source: https://www.evennia.com/docs/latest/Howtos/Tutorial-Using-Arxcode.html

Checkout the required version tag and install Evennia as a package.

```bash
cd evennia
git checkout tags/v0.7 -b arx-master
pip install -e .
```

--------------------------------

### Install AWS Dependencies

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-AWSStorage.html

Install the necessary boto3 dependency via pip.

```bash
pip install evennia[extra]
```

--------------------------------

### Configure and Start Dummy Clients

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/profiling/dummyrunner.html

Calculates action probabilities and initializes the DummyFactory to connect multiple clients to the server via the Twisted reactor.

```python
# make sure the probabilities add up to 1
pratio = 1.0 / sum(tup[0] for tup in actions[2:])
flogin, flogout, probs, cfuncs = (
    actions[0],
    actions[1],
    [tup[0] * pratio for tup in actions[2:]],
    [tup[1] for tup in actions[2:]],
)
# create cumulative probabilies for the random actions
cprobs = [sum(v for i, v in enumerate(probs) if i <= k) for k in range(len(probs))]
# rebuild a new, optimized action structure
actions = (flogin, flogout) + tuple(zip(cprobs, cfuncs))

# setting up all clients (they are automatically started)
factory = DummyFactory(actions)
for i in range(NCLIENTS):
    reactor.connectTCP("127.0.0.1", TELNET_PORT, factory)
# start reactor
reactor.run()
```

--------------------------------

### Start PostgreSQL Client

Source: https://www.evennia.com/docs/latest/Setup/Choosing-a-Database.html

Initiate a connection to the PostgreSQL service using the psql command-line client.

```bash
psql -U postgres --password
```

--------------------------------

### RedirectLink Example

Source: https://www.evennia.com/docs/latest/api/evennia.contrib.grid.xyzgrid.xymap_legend.html

Visual examples of valid and invalid path configurations for the RedirectLink.

```text
  /
-o    - this is ok, there can only be one path, e-ne

 |
-o-   - equivalent to '+', one n-s and one w-e link crossing
 |

\|/
-o-   - all are passing straight through
/|\

-o-   - w-e pass straight through, other link is sw-s
/|

-o    - invalid; impossible to know which input goes to which output
/|
```

--------------------------------

### Build multi-version documentation

Source: https://www.evennia.com/docs/latest/Contributing-Docs.html

Build documentation for multiple versions locally for verification.

```bash
make mv-local
```

--------------------------------

### Crafting Command Parsing Examples

Source: https://www.evennia.com/docs/latest/api/evennia.contrib.game_systems.crafting.crafting.html

Examples of the syntax used for the craft command.

```text
<recipe> [FROM <ingredients>] [USING <tools>]
```

```text
craft snowball from snow
craft puppet from piece of wood using knife
craft bread from flour, butter, water, yeast using owen, bowl, roller
craft fireball using wand, spellbook
```

--------------------------------

### Achievement command usage examples

Source: https://www.evennia.com/docs/latest/api/evennia.contrib.game_systems.achievements.achievements.html

Examples of how to use the achievements command in-game.

```text
achievements apples achievements/all achievements/progress rats
```

--------------------------------

### Create Project Directory

Source: https://www.evennia.com/docs/latest/Howtos/Tutorial-Using-Arxcode.html

Set up the local directory structure for source code.

```bash
cd ~
mkdir Source
cd Source
mkdir Arx
cd Arx
```

--------------------------------

### Tutorial Documentation Links

Source: https://www.evennia.com/docs/latest/_modules/evennia/contrib/tutorials/tutorial_world/intro_menu.html

URLs for accessing Evennia documentation and community resources.

```text
|yhttps://www.evennia.com/docs/latest|n
```

```text
|yhttps://www.evennia.com/docs/latest/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Building-Quickstart|n
```

```text
|yhttps://www.evennia.com/docs/latest/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Tutorial-World|n
```

```text
|yhttps://www.evennia.com/docs/latest/Howtos/Howtos-Overview|n
```

```text
|yhttps://www.evennia.com|n
```

--------------------------------

### Building Menu Interaction Example

Source: https://www.evennia.com/docs/latest/Contribs/Contrib-Building-Menu.html

Demonstrates the command-line output of the building menu when editing a room and navigating through exit choices.

```text
> @edit here
Building menu: A beautiful meadow

 [T]itle: A beautiful meadow
 [D]escription:
   This is a beautiful meadow.  But so beautiful I can't describe it.
 [E]xits:
  north
  south
 [Q]uit the menu

> e
-------------------------------------------------------------------------------

Room exits:
 Use @c to create a new exit.

Existing exits:
  @e north (n) toward north(#4)
  @e south (s) toward south(#7)

> @
Building menu: A beautiful meadow

 [T]itle: A beautiful meadow
 [D]escription:
   This is a beautiful meadow.  But so beautiful I can't describe it.
 [E]xits:
  north
  south
 [Q]uit the menu

> q
Closing the building menu.
```

--------------------------------

### Install debugpy dependency

Source: https://www.evennia.com/docs/latest/_sources/Contribs/Contrib-Debugpy.md.txt

Run this command within the virtual environment where Evennia is installed.

```bash
pip install debugpy
```

--------------------------------

### Initialize settings file

Source: https://www.evennia.com/docs/latest/_modules/evennia/server/evennia_launcher.html

Command to generate a new settings.py file when missing from the game directory.

```bash
evennia --initsettings
```

--------------------------------

### Install pip in virtualenv

Source: https://www.evennia.com/docs/latest/Setup/Installation-Troubleshooting.html

Command to install pip after creating a virtual environment without it.

```bash
python -m ensurepip --upgrade
```

--------------------------------

### Install reCAPTCHA Django App

Source: https://www.evennia.com/docs/latest/Howtos/Web-Character-Generation.html

Command to install the django-nocaptcha-recaptcha package via pip.

```bash
pip install django-nocaptcha-recaptcha
```

--------------------------------

### Execute Tutorial Batch File

Source: https://www.evennia.com/docs/latest/Components/Batch-Command-Processor.html

Command to execute the provided tutorial batch file example.

```text
> batchcommand contrib.tutorial_examples.batch_cmds
```

--------------------------------

### Install Evennia

Source: https://www.evennia.com/docs/latest/Setup/Installation-Android.html

Download and install the latest Evennia source code in editable mode.

```bash
(evenv) $ pip install --upgrade -e 'git+https://github.com/evennia/evennia#egg=evennia'
```

--------------------------------

### Accessing Help via Command Line

Source: https://www.evennia.com/docs/latest/_sources/Components/Help-System.md.txt

Examples of using the help command in-game to search for topics and view suggestions.

```shell
> help theatre
```

```shell
------------------------------------------------------------------------------
Help for The theatre (aliases: the hub, curtains)

The theatre is at the centre of the city, both literally and figuratively ...
(A lot more text about it follows ...)

Subtopics:
  theatre/lore
  theatre/layout
  theatre/dramatis personae
------------------------------------------------------------------------------
```

```shell
> help evennia
```

```shell
------------------------------------------------------------------------------
No help found

There is no help topic matching 'evennia'.
... But matches where found within the help texts of the suggestions below.

Suggestions:
  grapevine2chan, about, irc2chan
-----------------------------------------------------------------------------
```

--------------------------------

### Install Twitter Python Module

Source: https://www.evennia.com/docs/latest/Setup/Channels-to-Twitter.html

Install the required dependency for Twitter API interaction.

```bash
pip install python-twitter
```

--------------------------------

### Install django-test-without-migrations

Source: https://www.evennia.com/docs/latest/Coding/Unit-Testing.html

Install the package to allow running tests without executing migrations.

```bash
$ pip install django-test-without-migrations
```

--------------------------------

### Dice Command Examples

Source: https://www.evennia.com/docs/latest/api/evennia.contrib.rpg.dice.dice.html

Examples of how to use the dice command within the game interface.

```text
dice 3d6 + 4
dice 1d100 - 2 < 50
```

--------------------------------

### create_help(key, entrytext, category='General', locks=None, aliases=None, tags=None)

Source: https://www.evennia.com/docs/latest/_modules/evennia/help/manager.html

Creates a new static help entry in the database. This is intended for general game information rather than command-specific documentation.

```APIDOC
## Method: create_help

### Description
Creates a new static help entry in the help database. This method is used for general game help, setting information, or extensive documentation.

### Parameters
- **key** (str) - Required - The name of the help entry.
- **entrytext** (str) - Required - The body content of the help entry.
- **category** (str) - Optional - The help category of the entry (default: 'General').
- **locks** (str) - Optional - A lockstring to restrict access to the entry.
- **aliases** (list of str) - Optional - List of alternative keynames for the entry.
- **tags** (list) - Optional - List of tags or tuples (tag, category).

### Returns
- **HelpEntry** - The newly created help entry object, or None if creation fails.
```

--------------------------------

### Example URL pattern match

Source: https://www.evennia.com/docs/latest/Howtos/Web-Character-View-Tutorial.html

An example of the URL structure expected by the defined pattern.

```text
sheet/123/
```
Tokens:
Raw