### Quick Evennia Installation Steps

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

A condensed, step-by-step guide for quickly setting up Evennia from source using Git, Python virtual environments, and pip. This sequence covers cloning the repository, setting up the environment, installing Evennia, initializing a game, and starting the server.

```bash
git clone https://github.com/evennia/evennia.git
python3.11 -m venv evenv
source evenv/bin/activate
pip install -e evennia
evennia --init mygame
cd mygame
evennia migrate
evennia start
```

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

### Evennia Git Installation Quick Start

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

A concise, step-by-step guide to quickly install Evennia from source using Git. This includes cloning the repository, setting up a virtual environment, installing dependencies, and initializing/starting a new game. Note that virtual environment activation commands vary by operating system.

```Shell
git clone https://github.com/evennia/evennia.git
```

```Python
python3.11 -m venv evenv
```

```Shell
source evenv/bin/activate (Linux, Mac)
evenv\Scripts\activate (Windows)
```

```Shell
pip install -e evennia
```

```Shell
evennia --init mygame
```

```Shell
cd mygame
```

```Shell
evennia migrate
```

```Shell
evennia start
```

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

### Start Evennia Server with Live Logs

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Installation.md

This command starts the Evennia server and immediately begins tailing its logs in real-time. It combines the start and log viewing functionalities for convenience. This is useful for initial setup and debugging.

```Bash
evennia start -l
```

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

### Migrate and Start Evennia Game Server

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

Navigates into the newly created game directory, runs database migrations to set up the game's database, and then starts the Evennia game server. This sequence is necessary for the initial setup and launch of the game.

```Bash
cd mygame
evennia migrate
evennia start
```

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

### Start Evennia Server

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Installation.md

This command starts the Evennia game server. Upon first run, it will prompt for superuser credentials. The server will then be accessible via telnet or web browser. Ensure the database has been migrated first.

```Bash
evennia start
```

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

### Start Evennia Server and View Logs Simultaneously

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

This command starts the Evennia server while simultaneously beginning to view its real-time logs. This is convenient for monitoring server startup and initial operations.

```bash
evennia start -l
```

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

### Install Evennia via pip

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

Installs the Evennia game engine using the Python package installer, pip. This is the recommended and fastest way to get Evennia up and running.

```bash
pip install evennia
```

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

### Run Evennia Server

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

To run Evennia after initial setup, first navigate to your home directory and activate your virtual environment. Then, change into your game's directory and execute 'evennia start' to launch the game server. This sequence ensures the correct environment is active before starting the server.

```bash
$ cd ~ && source evenv/bin/activate
(evenv) $ cd mygame
(evenv) $ evennia start
```

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

### Start Evennia Server and Create Superuser

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

This command starts the Evennia server. Upon first run, it prompts for a username and password to create an in-game superuser account, which can also be automated. The server will then be accessible via telnet or web browser.

```bash
evennia start
```

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

### Start Evennia Game for the First Time

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

These commands navigate into your new game directory, run database migrations to set up the game's database schema, and then start the Evennia server. This is typically done once for a new game to prepare it for operation.

```bash
(evenv) $ cd mygame
(evenv) $ evennia migrate
(evenv) $ evennia start
```

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

### Start Evennia Container with Docker Compose

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Installation-Docker.md

This command starts the Evennia container defined in your `docker-compose.yml` file. It orchestrates the container setup, including port forwarding and volume mounts, making it simple to run your game in development.

```Shell
docker-compose up
```

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

### Install IPython for Enhanced Evennia Shell

Source: https://www.evennia.com/docs/latest/index.html/Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview

Install IPython to get a more interactive and user-friendly experience when using the `evennia shell`. If IPython is installed, `evennia shell` will automatically utilize it, providing features like tab completion and command history.

```Shell
$ pip install ipython3
```

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

### Display Evennia command line help

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

Shows the usage instructions and available options for the `evennia` command, useful for understanding its functionalities and arguments.

```bash
evennia -h
```

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

### Start Evennia Game Server

Source: https://www.evennia.com/docs/latest/index.html/Coding/Setting-up-PyCharm

Command to start the Evennia game server.

```Shell
evennia start
```

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

### Evennia Dummyrunner Setup and Execution Guide

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

This guide provides step-by-step instructions for setting up and running the Evennia dummyrunner for stress testing. It covers database preparation, settings.py modifications, server startup, dummyrunner execution, and notes on profiling and client scaling.

```Python
PERMISSION_ACCOUNT_DEFAULT="Builder"
```

```Shell
evennia --dummyrunner <nr_of_clients>
```

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

### Install Evennia with optional extra dependencies

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

Installs Evennia along with all additional packages required by optional contribs. Use this command if a contrib warns about missing dependencies.

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

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

### Evennia Server Initial Setup and Error Handling

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

This snippet illustrates the server's initial setup logic, distinguishing between a first-time start and resuming from a previous state. It ensures that the setup process is either initiated or continued from the last failed step, and includes robust error handling to stop the server and portal if the setup encounters an exception.

```Python
                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()
```

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

### Evennia XYZgrid Setup and Example Map Configuration

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

This snippet demonstrates how to set up the `evennia.contrib.grid.xyzgrid` launcher extension and provides example configurations for `ROOM_PARENT` and `EXIT_PARENT` prototypes. It also includes an ASCII art representation of a map (`MAP1`) used with the XYZgrid system, illustrating various map symbols.

```Python
"""
Example xymaps to use with the XYZgrid contrib. Build outside of the game using
the `evennia xyzgrid` launcher command.

First add the launcher extension in your mygame/server/conf/settings.py:

    EXTRA_LAUNCHER_COMMANDS['xyzgrid'] = 'evennia.contrib.grid.xyzgrid.launchcmd.xyzcommand'

Then

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

"""

from evennia.contrib.grid.xyzgrid import xymap_legend

# default prototype parent. It's important that
# the typeclass inherits from the XYZRoom (or XYZExit)
# if adding the evennia.contrib.grid.xyzgrid.prototypes to
# settings.PROTOTYPE_MODULES, one could just set the
# prototype_parent to 'xyz_room' and 'xyz_exit' here
# instead.

ROOM_PARENT = {
    "key": "An empty room",
    "prototype_key": "xyz_exit_prototype",
    # "prototype_parent": "xyz_room",
    "typeclass": "evennia.contrib.grid.xyzgrid.xyzroom.XYZRoom",
    "desc": "An empty room.",
}

EXIT_PARENT = {
    "prototype_key": "xyz_exit_prototype",
    # "prototype_parent": "xyz_exit",
    "typeclass": "evennia.contrib.grid.xyzgrid.xyzroom.XYZExit",
    "desc": "A path to the next location.",
}

# ---------------------------------------- map1
# The large tree
#
# this exemplifies the various map symbols
# but is not heavily prototyped

MAP1 = r"""
                       1
 + 0 1 2 3 4 5 6 7 8 9 0

 8   #-------#-#-------I
      \\               /
 7     #-#---#     t-#
       |\\    |
 6   #i#-#b--#-t
       |     |
 5     o-#---#
          \\ /
 4     o---#-#
      /    d
 3   #-----+-------#
           |       d
 2         |       |
           v       u
 1         #---#>#-#
          /
 0       #-T

 + 0 1 2 3 4 5 6 7 8 9 0
                       1
"""
```

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

### Install Evennia with Extra Dependencies

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Installation.md

This command installs Evennia along with all its optional extra dependencies. This is useful if you plan to use contribs that require additional packages. It ensures all necessary components are available.

```Bash
pip install evennia[extra]
```

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

### Start Evennia Container with Docker Compose

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

Executes the `docker-compose.yml` configuration to start the Evennia game container and its associated services, simplifying the container launch process.

```bash
docker-compose up
```

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

### Start Evennia Docker container with foreground logging

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

This command starts an Evennia Docker container, mapping necessary ports (4000, 4001, 4002) and mounting the current directory as the game source. It runs `evennia start -l` as the foreground process, echoing logs to the terminal, which is crucial for keeping the container alive.

```Docker
docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 --rm -v $PWD:/usr/src/game evennia/evennia evennia start -l
```

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

### Start Evennia Server with Log Output

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Online-Setup.md

Instructions to start the Evennia server and view its logs directly in the terminal. The `--log` (or `-l`) flag ensures logs are echoed to the terminal, useful for monitoring and debugging.

```Bash
evennia start --log
```

```Bash
evennia --log
```

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

### Run Evennia Server from Termux

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

Provides the full sequence of commands to start the Evennia server from a fresh Termux session. It includes navigating to the home directory, activating the virtual environment, changing to the game directory, and finally starting the Evennia server.

```Bash
cd ~ && source evenv/bin/activate
cd mygame
evennia start
```

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

### Evennia `at_initial_setup.py` Configuration File

Source: https://www.evennia.com/docs/latest/index.html/_sources/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Gamedir-Overview.md

This file allows developers to add custom actions that will be executed when Evennia starts up for the very first time. Basic tasks like creating the superuser and Limbo room are handled here by default.

```APIDOC
File: at_initial_setup.py
Purpose: Inject code to run only on the very first server startup.
Usage:
  - Add custom actions beyond default tasks (superuser, Limbo room creation).
```

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

### Execute Evennia Server Initial Setup Script

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

This method is triggered upon connection to the Evennia portal via the AMP protocol. It attempts to run the initial setup script specified by `settings.INITIAL_SETUP_MODULE`. It checks `last_initial_setup_step` in `ServerConfig` to determine if this is the first server start, only proceeding with setup if no previous step is recorded, indicating an empty database.

```Python
    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.
```

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

### API Reference: goto_command_demo_help Function

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

API documentation for the `goto_command_demo_help` function, which prepares the environment before transitioning to the help-demo node within the menu system.

```APIDOC
Function: goto_command_demo_help
  Signature: goto_command_demo_help(caller, raw_string, **kwargs)
  Description: Sets things up before going to the help-demo node
```

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

### Setup and Go to Color Demo Node (Evennia)

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

This function sets up and navigates to the color demonstration node within the Evennia tutorial world. It takes `caller`, `raw_string`, and `kwargs` as input.

```APIDOC
evennia.contrib.tutorials.tutorial_world.intro_menu.goto_command_demo_comms(*caller*, *raw_string*, **kwargs)
  Description: Setup and go to the color demo node.
```

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

### Install Evennia Tutorial World

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

To install the tutorial world, log in as superuser (#1) and execute this command. It builds the world, connects it to Limbo, and creates a new exit 'tutorial'. Allow time for the build to complete and avoid re-running the command if it's slow.

```Evennia Command
batchcommand contrib.tutorials.tutorial_world.build
```

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

### Getting Help: Listing All Available Commands

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

This command allows users to retrieve a comprehensive list of all commands accessible to them in the game.

```Evennia Commands
help
```

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

### Install Evennia Tutorial World

Source: https://www.evennia.com/docs/latest/index.html/_sources/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Tutorial-World.md

This command initiates the build script for the Evennia Tutorial World, which sets up the game environment. It runs a sequence of build commands from `evennia/contrib/tutorials/tutorial_world/build.ev`.

```Evennia Command
batchcommand tutorial_world.build
```

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

### Stop Evennia Server

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

This command fully stops the Evennia server. The server will remain offline until explicitly restarted using the `evennia start` command.

```bash
evennia stop
```

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

### Termux Command Prompt Example

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

Illustrates the typical command prompt in Termux, indicating that the '$' symbol should not be included when executing commands. This serves as a visual guide for users interacting with the terminal.

```Bash
cat file.txt
```

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

### Install Evennia Tutorial World

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

Run this command as a superuser (#1) to build and install the Evennia Tutorial World. It connects the new world to Limbo and creates a 'tutorial' exit. Allow some time for the building process to complete.

```Evennia Command
batchcommand contrib.tutorials.tutorial_world.build
```

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

### Setup and Go to Demo Room Node (Evennia)

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

This function sets up and navigates to a demo-room node within the Evennia tutorial world. It generates a small 2-room environment for testing commands. It takes `caller`, `raw_string`, and `kwargs` as input.

```APIDOC
evennia.contrib.tutorials.tutorial_world.intro_menu.goto_command_demo_room(*caller*, *raw_string*, **kwargs)
  Description: Setup and go to the demo-room node. Generates a little 2-room environment for testing out some commands.
```

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

### Stop Evennia Server

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Installation.md

This command completely stops the running Evennia server. All connections will be terminated. To restart the server, you will need to use the 'evennia start' command again. This is for full shutdown.

```Bash
evennia stop
```

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

### EvAdventure Folder Structure Setup

Source: https://www.evennia.com/docs/latest/index.html/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Utilities

Illustrates the recommended folder structure for the EvAdventure tutorial, showing the placement of the `evadventure` and `tests` directories within `mygame`, along with necessary `__init__.py` files to define Python packages.

```text
mygame/
   commands/
   evadventure/         <---
      __init__.py       <---
      tests/            <---
          __init__.py   <---
   __init__.py
   README.md
   server/
   typeclasses/
   web/
   world/
```

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

### Connect to MySQL/MariaDB as Root User

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

Command to start the MySQL/MariaDB client from the terminal and log in as the root user, prompting for the password. This is typically the first step after installing the database server.

```bash
mysql -u root -p
```

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

### Evennia `web_plugins.py` Configuration File

Source: https://www.evennia.com/docs/latest/index.html/_sources/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Gamedir-Overview.md

This file provides the functionality to add plugins to the Evennia webserver as it starts up.

```APIDOC
File: web_plugins.py
Purpose: Add plugins to the Evennia webserver during startup.
```

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

### Virtualenv Setup Error Message Example

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

This snippet illustrates a common error message received when the `python3.x -m venv evenv` command fails, typically indicating an issue with `ensurepip` during virtual environment creation.

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

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

### Bootstrap Virtualenv Without Pip

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

This command creates a virtual environment without installing pip initially, which can be a workaround for `venv` setup errors. After creation, pip can be installed separately within the activated environment to complete the setup.

```Bash
python3.x -m --without-pip evenv
```

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

### Install Evennia Tutorial World

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

This command installs the Evennia Tutorial World, a small MUD-style game world, by executing a build script. It runs a sequence of build-commands from 'evennia/contrib/tutorials/tutorial_world/build.ev' and should only be run once to avoid potential issues.

```Evennia Command
batchcommand tutorial_world.build
```

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

### Python Example Two: Map Setup for Exit Generation

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

This Python snippet provides the initial setup for Example 2, indicating the command to run it and the necessary imports. It notes that this example will focus on incorporating characters for exit generation, building upon the map layout from Example 1.

```Python
# @mapbuilder/two evennia.contrib.grid.mapbuilder.EXAMPLE2_MAP EXAMPLE2_LEGEND

# -*- coding: utf-8 -*-

# Add the necessary imports for your instructions here.
# from evennia import create_object
# from typeclasses import rooms, exits
# from evennia.utils import utils
# from random import randint
# import random

# This is the same layout as Example 1 but included are characters for exits.
```

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

### Customizable initial_setup.py via settings.py

Source: https://www.evennia.com/docs/latest/index.html/Coding/Release-Notes-1.0

The `initial_setup.py` file can now be substituted in `settings.py`, allowing customization of the initial game database state.

```APIDOC
Initial Setup: `initial_setup.py`
  Feature: Substitutable via `settings.py`
  Benefit: Customize initial game database state.
```

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

### Virtualenv Setup Error Message Example

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

This snippet shows a common error message encountered when the `python3.x -m venv evenv` command fails. It indicates an issue with `ensurepip` or a non-zero exit status during the virtual environment creation process.

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

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

### Evennia: New Game Directory Creation Message

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

This message is displayed when a new Evennia game directory is successfully created, providing instructions for initial setup, database migration, and server startup. It guides the user through the first steps to get their Evennia project running.

```Plain Text
Welcome to Evennia!
Created a new Evennia game directory '{gamedir}'.

You can now optionally edit your new settings file
at {settings_path}. If you don't, the defaults
will work out of the box. When ready to continue, 'cd' to your
game directory and run:

   evennia migrate

This initializes the database. To start the server for the first
time, run:

   evennia start

Make sure to create a superuser when asked for it (the email is optional)
You should now be able to connect to your server on 'localhost', port 4000
using a telnet/mud client or http://localhost:4001 using your web browser.
If things don't work, check the log with `evennia --log`. Also make sure
ports are open.

(Finally, why not run `evennia connections` and make the world aware of
your new Evennia project!)
```

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

### Python: Limbo Room Welcome Description

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

Defines the welcome message displayed to users in the default 'Limbo' room, providing guidance on building tutorial content and accessing help resources.

```Python
LIMBO_DESC = _(
    """
Welcome to your new |wEvennia|n-based game! Visit https://www.evennia.com if you need
help, want to contribute, report issues or just join the community.

As a privileged user, write |wbatchcommand tutorial_world.build|n to build
tutorial content. Once built, try |wintro|n for starting help and |wtutorial|n to
play the demo game.
"""
)
```

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

### Install Evennia with pip

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Installation.md

This command installs the Evennia game server using Python's pip package manager. It's recommended to use a virtual environment for isolated installation. This command installs the core Evennia package.

```Bash
pip install evennia
```

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

### Upgrade Evennia installation

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

Upgrades an existing Evennia installation to the latest version available on PyPI. This command ensures you have the most recent features and bug fixes.

```bash
pip install --upgrade evennia
```

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

### API Documentation for TutorialStartExit Class

Source: https://www.evennia.com/docs/latest/index.html/api/evennia.contrib.tutorials.tutorial_world.rooms

Documents the `TutorialStartExit` class, a specialized exit type that provides the 'intro' command. It details its inheritance, creation hook, and associated exceptions and attributes.

```APIDOC
class evennia.contrib.tutorials.tutorial_world.rooms.TutorialStartExit(*args, **kwargs):
  Bases: evennia.objects.objects.DefaultExit
  Description: This is like a normal exit except it makes the intro command available on itself. We put it on the exit in order to provide this command to the Limbo room without modifying Limbo itself - deleting the tutorial exit will also clean up the intro command.

  Methods:
    at_object_creation()
      Description: Called once, when this object is first created. This is the normal hook to overload for most object types.

  Exceptions:
    DoesNotExist
      Bases: evennia.objects.objects.DefaultExit.DoesNotExist
    MultipleObjectsReturned
      Bases: evennia.objects.objects.DefaultExit.MultipleObjectsReturned

  Attributes:
    path: 'evennia.contrib.tutorials.tutorial_world.rooms.TutorialStartExit'
    typename: 'TutorialStartExit'
```

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

### Evennia: Querying typeclasses and subclasses with filter_family()

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

To overcome the limitation of `get()` and `filter()` not including subclasses, Evennia provides `filter_family()` and `get_family()` methods. This example uses `filter_family()` to search for all `Furniture` instances and their subclasses whose `db_key` starts with 'Chair', ensuring a broader search across the typeclass hierarchy.

```Python
# search for all furnitures and subclasses of furnitures
# whose names starts with "Chair"
matches = Furniture.objects.filter_family(db_key__startswith="Chair")
```

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

### Creating a Basic Object

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

Demonstrates the `create` command to instantiate a new object of the default type, placing it into the player's inventory.

```Evennia Command
create box
```

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

### Example: Creating and Dropping an Object

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

This provides a concrete example of using a command with a switch to perform an action, specifically creating and dropping a 'box' object.

```Evennia Commands
create/drop box
```

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

### Example: Creating an Object with Switches

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

This example demonstrates the 'create' command with the '/drop' switch and the argument 'box'. It shows how to use a switch to modify command behavior, in this case, creating a 'box' that is also dropped.

```Evennia Command
create/drop box
```

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

### Installing Evennia Documentation Build Dependencies

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

Commands to install the necessary Python packages required for building the Evennia documentation. Users can choose between using `make install` or `pip install -r requirements.txt`.

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

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

### Configure and Build XYZgrid Maps

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

Instructions to add the `xyzgrid` launcher command to Evennia and build example maps. This involves modifying the `settings.py` file and executing a series of `evennia xyzgrid` commands from the shell.

```Python
EXTRA_LAUNCHER_COMMANDS['xyzgrid'] = 'evennia.contrib.grid.xyzgrid.launchcmd.xyzcommand'
```

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

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

### Install documentation build requirements

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

Installs the necessary Python packages for building Evennia documentation, either using `make install` or directly via `pip` from `requirements.txt`.

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

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

### Install Evennia via pip

Source: https://www.evennia.com/docs/latest/index.html/Coding/Release-Notes-1.0

Evennia 1.0 can now be installed directly from PyPi using pip, simplifying the setup process.

```bash
pip install evennia
```

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

### Creating a TutorialMirror Object

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

Demonstrates how to create an instance of the `TutorialMirror` object in Evennia using the `create/drop` command, specifying its Python path.

```Evennia Command Line
> create/drop mirror:contrib.tutorials.mirror.TutorialMirror
```

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

### Install Evennia AWS Dependencies with pip

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

This command installs the required 'boto3' Python package, which is the official AWS SDK, by installing Evennia's extra requirements. It supports both standard pip installations and installations from a Git repository, ensuring all necessary dependencies for AWS integration are met.

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

```bash
pip install --upgrade -e .[extra]
```

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

### Create New Django App for Evennia Web

Source: https://www.evennia.com/docs/latest/index.html/Howtos/Web-Help-System-Tutorial

Commands to navigate to the 'web' directory and initialize a new Django application named 'help_system' using Evennia's `startapp` utility. This creates the basic directory structure for the new app.

```bash
cd web
evennia startapp help_system
```

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

### Accessing In-Game Help

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

The 'help' command provides a list of all available commands to the player. To get specific information about a particular command, append the command's name to 'help'.

```Evennia Command
help
```

```Evennia Command
help <commandname>
```

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

### Update Evennia Installation using pip

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Updating-Evennia.md

Provides a step-by-step guide to upgrade an Evennia installation that was originally installed using pip. It covers stopping Evennia, upgrading the package, running migrations, and restarting the server.

```bash
cd mygame
evennia stop
pip install --upgrade evennia
evennia migrate
evennia start
```

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

### Upgrade Evennia Installation

Source: https://www.evennia.com/docs/latest/index.html/_sources/Setup/Installation.md

This command upgrades an existing Evennia installation to the latest version available on PyPI. It ensures your game server is running with the most recent features and bug fixes. Run this after activating your virtual environment.

```Bash
pip install --upgrade evennia
```

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

### Install Evennia via pip

Source: https://www.evennia.com/docs/latest/index.html/Coding/Setting-up-PyCharm

Instructions to install the Evennia game engine using pip within a virtual environment.

```Shell
pip install evennia
```

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

### Initialize EvMenu Instance

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

Demonstrates how to create and configure an EvMenu instance, specifying the caller, menu module path, start node, command set options, and persistence.

```python
    from evennia.utils.evmenu import EvMenu

    EvMenu(caller, menu_module_path,
         startnode="node1",
         cmdset_mergetype="Replace", cmdset_priority=1,
         auto_quit=True, cmd_on_exit="look", persistent=True)
```

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

### Getting Help: Viewing Specific Command Details

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

Use this command to get detailed in-game help and usage information for a particular command by specifying its name.

```Evennia Commands
help <commandname>
```

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

### Enable Evennia command on Windows

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

For Windows users, this command permanently makes the `evennia` command available in your environment after the initial installation. It should be run once.

```bash
python -m evennia
```

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

### EvMenu Goto Callback: `goto_command_demo_help`

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

A goto callback function that prepares the environment for the help command demonstration. It dynamically manages command sets, removing other demo sets and adding `DemoCommandSetHelp` to ensure the correct commands are active for the user.

```Python
def goto_command_demo_help(caller, raw_string, **kwargs):
    "Sets things up before going to the help-demo node"
    _maintain_demo_room(caller, delete=True)
    caller.cmdset.remove(DemoCommandSetRoom)
    caller.cmdset.remove(DemoCommandSetComms)
    caller.cmdset.add(DemoCommandSetHelp)  # TODO - make persistent
    return kwargs.get("gotonode") or "command_demo_help"
```

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

### Setting Up Evennia Project Directory on Linux

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

Commands to create a new directory for Evennia development and navigate into it, preparing the location for cloning the Evennia repository.

```bash
mkdir muddev
cd muddev
```

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

### API: Create Initial Evennia Objects

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

Creates the #1 account and Limbo room, essential for the initial game setup.

```APIDOC
evennia.server.initial_setup.create_objects()
```

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

### Install ContainerCmdSet to CharacterCmdSet

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

To install the container system, import and add the `ContainerCmdSet` to `CharacterCmdSet` in your `default_cmdsets.py` file. This replaces default `look` and `get` commands and adds a `put` command.

```Python
from evennia.contrib.game_systems.containers import ContainerCmdSet

class CharacterCmdSet(default_cmds.CharacterCmdSet):
    # ...

    def at_cmdset_creation(self):
        # ...
        self.add(ContainerCmdSet)
```

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

### Initialize and Use EvEditor for In-Game Text Editing

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

This Python snippet demonstrates how to import and initialize the EvEditor for managing in-game text. It shows the setup of optional load, save, and quit functions to interact with a caller's attributes, such as a 'desc' attribute. The example illustrates how to start the editor with various configuration options like persistence and code formatting.

```python
from evennia.utils.eveditor import EvEditor

# set up an editor to edit the caller's 'desc' Attribute
def _loadfunc(caller):
    return caller.db.desc

def _savefunc(caller, buffer):
    caller.db.desc = buffer.strip()
    return True

def _quitfunc(caller):
    caller.msg("Custom quit message")

# start the editor
EvEditor(caller, loadfunc=None, savefunc=None, quitfunc=None, key="",
         persistent=True, code=False)
```

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

### AWS IAM Policy for Evennia S3 Access

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

This JSON policy defines the necessary permissions for an AWS IAM user or role to interact with S3 buckets for Evennia. It grants permissions for object manipulation (Put, Get, Delete, ACL) and bucket listing. An optional CreateBucket permission is included for initial setup, which can be removed later.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "evennia",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObjectAcl",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:PutObjectAcl"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME/*",
                "arn:aws:s3:::YOUR_BUCKET_NAME"
            ]
        }
    ],
    [
      {
         "Sid":"evennia",
         "Effect":"Allow",
         "Action":[
            "s3:CreateBucket",
         ],
         "Resource":[
            "arn:aws:s3:::*"
         ]
       }
    ]
}
```

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

### Evennia Command Syntax Overview

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

This snippet illustrates the general syntax for Evennia commands, which is similar to MUX. It includes optional switches, arguments, and the use of an equal sign for assignments.

```Evennia Commands
command[/switch/switch...] [arguments ...]
```

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

### AttributeHandler Method Usage Examples

Source: https://www.evennia.com/docs/latest/index.html/_sources/Components/Attributes.md

Practical examples demonstrating the usage of `AttributeHandler` methods: `get()` with `raise_exception` and `default` parameters, `remove()` for deleting attributes, and `all()` for retrieving attributes by category.

```python
try:
  # raise error if Attribute foo does not exist
  val = obj.attributes.get("foo", raise_exception=True):
except AttributeError:
   # ...

# return default value if foo2 doesn't exist
val2 = obj.attributes.get("foo2", default=[1, 2, 3, "bar"])

# delete foo if it exists (will silently fail if unset, unless
# raise_exception is set)
obj.attributes.remove("foo")

# view all clothes on obj
all_clothes = obj.attributes.all(category="clothes")
```

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

### Creating a TutorialMirror Object

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

Demonstrates how to instantiate a `TutorialMirror` object using Evennia's `create` command. This object is useful for testing as it echoes back any messages sent to it.

```Evennia Command
create/drop mirror:contrib.tutorials.mirror.TutorialMirror
```

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

### Evennia `at_server_startstop.py` Configuration File

Source: https://www.evennia.com/docs/latest/index.html/_sources/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Gamedir-Overview.md

This file provides a mechanism to inject custom code that executes every time the Evennia server starts, stops, or reloads in various ways.

```APIDOC
File: at_server_startstop.py
Purpose: Inject code to execute on server start, stop, or reload events.
```

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

### Examples of Evennia lock string definitions

Source: https://www.evennia.com/docs/latest/index.html/_sources/Components/Locks.md

Provides various examples of lock string definitions, demonstrating how to restrict actions like 'delete', 'edit', and 'get'. Examples include restricting by object ID, allowing 'all' access, and using attribute or permission checks with logical operators.

```Python
delete:id(34)   # only allow obj #34 to delete
edit:all()      # let everyone edit
# only those who are not "very_weak" or are Admins may pick this up
get: not attr(very_weak) or perm(Admin)
```

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

### Evennia Game Directory: server/ Folder API

Source: https://www.evennia.com/docs/latest/index.html/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Gamedir-Overview

Documents the structure and key files within the `server/` folder, which contains essential resources for running Evennia and whose structure should be preserved.

```APIDOC
server/
  conf/
    settings.py: Most important server configuration file.
  logs/: Server log files. `evennia --log` tails files here.
  evennia.db3: (Only with default SQLite3) Contains the entire database.
    Backup: Copy the file.
    Reset: Copy a pre-configured backup or delete to recreate with `evennia migrate`.
```

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

### Install Evennia Extra Dependencies for XYZgrid

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

Installs the `scipy` library and other optional requirements for Evennia, which are necessary for the XYZGrid contribution to function correctly. This is the easiest method to get all required dependencies.

```Shell
pip install evennia[extra]
```

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

### MyST Deprecated Directive Example

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

Shows the `deprecated` directive, indicating a feature that is no longer recommended for use from a specific version. This guides users away from outdated functionalities.

```APIDOC
```{deprecated} 1.0
```
```