From fdda358930c870dfb75d82ae1710bbf875d37b4c Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 5 Jul 2026 08:57:43 +0200 Subject: [PATCH] Update docs --- CHANGELOG.md | 4 +- docs/source/Coding/Changelog.md | 29 +++++- .../Contribs/Contrib-Database-Backup.md | 89 +++++++++++++++++++ docs/source/Contribs/Contribs-Overview.md | 29 ++++-- docs/source/Setup/Settings-Default.md | 27 +++++- ...b.utils.database_backup.database_backup.md | 10 +++ .../evennia.contrib.utils.database_backup.md | 18 ++++ ...nia.contrib.utils.database_backup.tests.md | 10 +++ docs/source/api/evennia.contrib.utils.md | 1 + docs/source/api/evennia.server.is_typing.md | 10 +++ docs/source/api/evennia.server.md | 1 + docs/source/index.md | 2 +- evennia/VERSION.txt | 2 +- pyproject.toml | 2 +- 14 files changed, 217 insertions(+), 17 deletions(-) create mode 100644 docs/source/Contribs/Contrib-Database-Backup.md create mode 100644 docs/source/api/evennia.contrib.utils.database_backup.database_backup.md create mode 100644 docs/source/api/evennia.contrib.utils.database_backup.md create mode 100644 docs/source/api/evennia.contrib.utils.database_backup.tests.md create mode 100644 docs/source/api/evennia.server.is_typing.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 978e358dca..54a352b6b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,8 @@ # Changelog -## Main branch +## Evennia 6.1.0 + +July 5, 2026 - Feat: Add AGENTS.md and .agents context files to aid AI agent development (Griatch) - Feat: Add `uv.lock` for Evennia library developers wanting to use the `uv` tool (Griatch) diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md index b4e56d0311..54a352b6b9 100644 --- a/docs/source/Coding/Changelog.md +++ b/docs/source/Coding/Changelog.md @@ -1,6 +1,8 @@ # Changelog -## Main branch +## Evennia 6.1.0 + +July 5, 2026 - Feat: Add AGENTS.md and .agents context files to aid AI agent development (Griatch) - Feat: Add `uv.lock` for Evennia library developers wanting to use the `uv` tool (Griatch) @@ -10,6 +12,11 @@ Existing clients are unaffected. (daiimus) - [Feat][pull3511]: Add `article` and `format` kwargs to `$You()`/`$you()`/`$Your()`/`$your()`. `$You()` now auto-capitalizes names for third-person receivers. (chiizujin) +- [Feat][pull3939]: Make AttributeProperty and NAttributeProperty generic for type inference (Problematic) +- [Feat][pull3940]: Add @overload signatures to TagHandler.get() for type narrowing (Problematic) +- [Feat][pull3917]: Add configurable server lifecycle broadcast messages (blongden) +- [Feat][pull3644]: Add database_backup contrib for scheduled database backups (aMiss-aWry) +- [Feat][pull3510]: Webclient is-typing indicator when others are typing emotes in same location (michaelfaith84) - [Fix][pull3866]: Fix 'None' showing up in Evennia startup log (jaborsh) - [Fix][pull3869]: Handle `evennia -l &` for non-Windows systems (jaborsh) - Fix: Improve indentation/formatting for east-asian languages (Griatch, with inspiration from hhsiao) @@ -36,7 +43,14 @@ - [Fix][issue3890]: Log RuntimeErrors during auto-puppet on login instead of silently swallowing them (Griatch) - Fix: MSSP game name now uses settings.SERVERNAME instead of hardcoded "Mygame" default (Griatch) -- Docs: Griatch, BigJMoney +- [Fix][pull3911]: Fix cmdset merge cache, improving performance up to 500x (kvmet) +- [Fix][pull3913]: Fix tag/search failing when searching by category only (blongden) +- [Fix][pull3914]: Fix NAWS stale-width on terminal resize and 'autoresize' client-option validation (michaelfaith84) +- [Fix][pull3936]: Add -> bool return annotations to override-intended hook methods (Problematic) +- [Fix][pull3938]: Fix ReferenceError in notifications plugin when window unfocused (Problematic) +- [Fix][pull3942]: Add AMP_CONNECT_TIMEOUT for portal probe (jaborsh) +- Fix: Resolve UnhandledCommand race on server start (Griatch) +- Docs: Griatch, BigJMoney, dicnunz, pikammmmm, InspectorCaracal [pull3866]: https://github.com/evennia/evennia/pull/3866 [pull3867]: https://github.com/evennia/evennia/pull/3867 @@ -54,11 +68,22 @@ [pull3905]: https://github.com/evennia/evennia/pull/3905 [pull3909]: https://github.com/evennia/evennia/pull/3909 [pull3910]: https://github.com/evennia/evennia/pull/3910 +[pull3911]: https://github.com/evennia/evennia/pull/3911 +[pull3913]: https://github.com/evennia/evennia/pull/3913 +[pull3914]: https://github.com/evennia/evennia/pull/3914 +[pull3936]: https://github.com/evennia/evennia/pull/3936 +[pull3938]: https://github.com/evennia/evennia/pull/3938 +[pull3939]: https://github.com/evennia/evennia/pull/3939 +[pull3940]: https://github.com/evennia/evennia/pull/3940 +[pull3917]: https://github.com/evennia/evennia/pull/3917 +[pull3644]: https://github.com/evennia/evennia/pull/3644 +[pull3942]: https://github.com/evennia/evennia/pull/3942 [pull3504]: https://github.com/evennia/evennia/pull/3504 [pull3511]: https://github.com/evennia/evennia/pull/3511 [pull3600]: https://github.com/evennia/evennia/pull/3600 [pull3769]: https://github.com/evennia/evennia/pull/3769 [pull3850]: https://github.com/evennia/evennia/pull/3850 +[pull3510]: https://github.com/evennia/evennia/pull/3510 [issue3890]: https://github.com/evennia/evennia/issues/3890 [issue3895]: https://github.com/evennia/evennia/issues/3895 [mudstandards-ws]: https://mudstandards.org/websocket/ diff --git a/docs/source/Contribs/Contrib-Database-Backup.md b/docs/source/Contribs/Contrib-Database-Backup.md new file mode 100644 index 0000000000..50efd17120 --- /dev/null +++ b/docs/source/Contribs/Contrib-Database-Backup.md @@ -0,0 +1,89 @@ +# Database Backup Scheduler + +Contribution by helpme (2024) + +This module schedules backups in-game, which saves a copy of your database to your game's `server/backups` folder. Database backups are *not* automatically uploaded to any cloud service, it is left to you to decide what to do with them (i.e. pushed to git, uploaded to the ether, downloaded to a hard drive). + +Backups can take place at any time. Restoring the game world from backup takes place during downtime, as documented below. + +Currently, the sqlite3 (the evennia default) and postgresql databases are supported. Others are welcome to add more. + +## Installation + +This utility adds the `backup` command. The `backup` command can be used to set up a scheduled backup script, or trigger the script to run immediately. The backup script makes a backup of your game world. Import the module into your commands and add it to your command set to make it available. + +In `mygame/commands/default_cmdsets.py`: + +```python +... +from evennia.contrib.utils.database_backup import DbCmdSet # <--- + +class CharacterCmdset(default_cmds.Character_CmdSet): + ... + def at_cmdset_creation(self): + ... + self.add(DbCmdSet) # <--- + +``` + +Then `reload` to make the `backup` command available. + +If you prefer to run the script without the `backup` command, you can manage it as a global script in your settings: + +```python +# in mygame/server/conf/settings.py + +GLOBAL_SCRIPTS = { + "backupscript": { + "typeclass": "evennia.contrib.utils.database_backup.DatabaseBackupScript", + "repeats": -1, + "interval": 86400, + "desc": "Database backup script" + }, +} +``` + +## Permissions + +By default, the backup command is only available to those with Developer permissions and higher. You can change this by overriding the command and setting its locks from "cmd:pperm(Developer)" to the lock of your choice. + +## Settings Used + +This utility uses the settings.DATABASES dictionary. + +## Restoration + +Remember to `evennia stop` before restoring your db. + +### Restoring sqlite3 (.db3) + +* Copy the database backup you want to restore from back into the `server/` directory +* By default (unless you changed the name of the file in `settings DATABASES`), the game data is expected to be located in the sqlite3 file `mygame/server/evennia.db3`. Copy your backup file over this file to recover your backup. + +### Restoring postgres (.sql) + +* Prepare the following variables +``` +export DB_USER=db_user # db_user from your settings.DATABASES +export DB_NAME=db_name # db_name from your settings.DATABASES +export BACKUP_FILE=backup_file_path # the path to the backup file you are restoring from +export PGPASSWORD=db_password # the password to your db + +If you prefer not to export your password to an env variable, you can enter it when prompted instead. +``` +* Run the following commands +``` +# Drop the existing database if it exists +psql -U $DB_USER -c "DROP DATABASE IF EXISTS $DB_NAME;" || exit 1 + +# Recreate the database +psql -U $DB_USER -c "CREATE DATABASE $DB_NAME;" || exit 1 + +# Restore the database from the backup file +psql -U $DB_USER -d $DB_NAME -f $BACKUP_FILE || exit 1 +``` + +---- + +This document page is generated from `evennia/contrib/utils/database_backup/README.md`. Changes to this +file will be overwritten, so edit that file rather than this one. diff --git a/docs/source/Contribs/Contribs-Overview.md b/docs/source/Contribs/Contribs-Overview.md index 0f40423933..517e32bfca 100644 --- a/docs/source/Contribs/Contribs-Overview.md +++ b/docs/source/Contribs/Contribs-Overview.md @@ -7,7 +7,7 @@ in the [Community Contribs & Snippets][forum] forum. _Contribs_ are optional code snippets and systems contributed by the Evennia community. They vary in size and complexity and may be more specific about game types and styles than 'core' Evennia. -This page is auto-generated and summarizes all **53** contribs currently included +This page is auto-generated and summarizes all **54** contribs currently included with the Evennia distribution. All contrib categories are imported from `evennia.contrib`, such as @@ -32,14 +32,14 @@ If you want to add a contrib, see [the contrib guidelines](./Contribs-Guidelines | [achievements](#achievements) | [auditing](#auditing) | [awsstorage](#awsstorage) | [barter](#barter) | [batchprocessor](#batchprocessor) | | [bodyfunctions](#bodyfunctions) | [buffs](#buffs) | [building_menu](#building_menu) | [character_creator](#character_creator) | [clothing](#clothing) | | [color_markups](#color_markups) | [components](#components) | [containers](#containers) | [cooldowns](#cooldowns) | [crafting](#crafting) | -| [custom_gametime](#custom_gametime) | [debugpy](#debugpy) | [dice](#dice) | [email_login](#email_login) | [evadventure](#evadventure) | -| [evscaperoom](#evscaperoom) | [extended_room](#extended_room) | [fieldfill](#fieldfill) | [gendersub](#gendersub) | [git_integration](#git_integration) | -| [godotwebsocket](#godotwebsocket) | [health_bar](#health_bar) | [ingame_map_display](#ingame_map_display) | [ingame_python](#ingame_python) | [ingame_reports](#ingame_reports) | -| [llm](#llm) | [mail](#mail) | [mapbuilder](#mapbuilder) | [menu_login](#menu_login) | [mirror](#mirror) | -| [multidescer](#multidescer) | [mux_comms_cmds](#mux_comms_cmds) | [name_generator](#name_generator) | [puzzles](#puzzles) | [random_string_generator](#random_string_generator) | -| [red_button](#red_button) | [rpsystem](#rpsystem) | [simpledoor](#simpledoor) | [slow_exit](#slow_exit) | [storage](#storage) | -| [talking_npc](#talking_npc) | [traits](#traits) | [tree_select](#tree_select) | [turnbattle](#turnbattle) | [tutorial_world](#tutorial_world) | -| [unixcommand](#unixcommand) | [wilderness](#wilderness) | [xyzgrid](#xyzgrid) | +| [custom_gametime](#custom_gametime) | [database_backup](#database_backup) | [debugpy](#debugpy) | [dice](#dice) | [email_login](#email_login) | +| [evadventure](#evadventure) | [evscaperoom](#evscaperoom) | [extended_room](#extended_room) | [fieldfill](#fieldfill) | [gendersub](#gendersub) | +| [git_integration](#git_integration) | [godotwebsocket](#godotwebsocket) | [health_bar](#health_bar) | [ingame_map_display](#ingame_map_display) | [ingame_python](#ingame_python) | +| [ingame_reports](#ingame_reports) | [llm](#llm) | [mail](#mail) | [mapbuilder](#mapbuilder) | [menu_login](#menu_login) | +| [mirror](#mirror) | [multidescer](#multidescer) | [mux_comms_cmds](#mux_comms_cmds) | [name_generator](#name_generator) | [puzzles](#puzzles) | +| [random_string_generator](#random_string_generator) | [red_button](#red_button) | [rpsystem](#rpsystem) | [simpledoor](#simpledoor) | [slow_exit](#slow_exit) | +| [storage](#storage) | [talking_npc](#talking_npc) | [traits](#traits) | [tree_select](#tree_select) | [turnbattle](#turnbattle) | +| [tutorial_world](#tutorial_world) | [unixcommand](#unixcommand) | [wilderness](#wilderness) | [xyzgrid](#xyzgrid) | @@ -804,6 +804,7 @@ Contribs-Guidelines.md :maxdepth: 1 Contrib-Auditing.md +Contrib-Database-Backup.md Contrib-Debugpy.md Contrib-Fieldfill.md Contrib-Git-Integration.md @@ -825,6 +826,16 @@ quality assurance, post-incident investigations and debugging. +### `database_backup` + +_Contribution by helpme (2024)_ + +This module schedules backups in-game, which saves a copy of your database to your game's `server/backups` folder. Database backups are *not* automatically uploaded to any cloud service, it is left to you to decide what to do with them (i.e. pushed to git, uploaded to the ether, downloaded to a hard drive). + +[Read the documentation](./Contrib-Database-Backup.md) - [Browse the Code](evennia.contrib.utils.database_backup) + + + ### `debugpy` _Contribution by electroglyph, 2025_ diff --git a/docs/source/Setup/Settings-Default.md b/docs/source/Setup/Settings-Default.md index 318585740a..38c5f4a0dc 100644 --- a/docs/source/Setup/Settings-Default.md +++ b/docs/source/Setup/Settings-Default.md @@ -172,6 +172,10 @@ EVENNIA_ADMIN = True AMP_HOST = "localhost" AMP_PORT = 4006 AMP_INTERFACE = "127.0.0.1" +# Timeout (seconds) for the launcher's connection to the Portal's AMP port when +# sending start/stop/status instructions. This is a loopback connection, so a +# live Portal accepts in well under a millisecond. +AMP_CONNECT_TIMEOUT = 2 # Path to the lib directory containing the bulk of the codebase's code. @@ -333,6 +337,10 @@ AUDIT_MASKS = [ ] # Broadcast "Server restart"-like messages to all sessions. BROADCAST_SERVER_RESTART_MESSAGES = True +# Messages broadcast to all sessions on server lifecycle events. +SERVER_RELOAD_INITIATE_MSG = " Server restart initiated {reason}..." +SERVER_RESET_MSG = " Server resetting/restarting ..." +SERVER_RESTART_MSG = " ... Server restarted." ###################################################################### # Evennia Database config @@ -500,10 +508,14 @@ LOCK_FUNC_MODULES = ("evennia.locks.lockfuncs", "server.conf.lockfuncs") # Module holding handlers for managing incoming data from the client. These # will be loaded in order, meaning functions in later modules may overload # previous ones if having the same name. -INPUT_FUNC_MODULES = ["evennia.server.inputfuncs", "server.conf.inputfuncs"] +INPUT_FUNC_MODULES = [ + "evennia.server.inputfuncs", + "server.conf.inputfuncs", + "evennia.server.is_typing", +] # Modules that contain prototypes for use with the spawner mechanism. PROTOTYPE_MODULES = ["world.prototypes"] -# Modules containing Prototype functions able to be embedded in prototype +# Modules containining Prototype functions able to be embedded in prototype # definitions from in-game. PROT_FUNC_MODULES = ["evennia.prototypes.protfuncs"] # Module holding settings/actions for the dummyrunner program (see the @@ -559,6 +571,10 @@ CMDSET_ACCOUNT = "commands.default_cmdsets.AccountCmdSet" # Location to search for cmdsets if full path not given CMDSET_PATHS = ["commands", "evennia", "evennia.contrib"] +# Max number of merged cmdsets to keep cached. When full, the least recently used +# entry is evicted. Increase if your game has many unique rooms/objects; decrease +# to save memory. +CMDSET_MERGE_CACHE_MAXSIZE = 1000 # Fallbacks for cmdset paths that fail to load. Note that if you change the path for your # default cmdsets, you will also need to copy CMDSET_FALLBACKS after your change in your # settings file for it to detect the change. @@ -1049,6 +1065,13 @@ STATICFILES_IGNORE_PATTERNS = ["README.md"] # directory names shown in the templates directory. WEBSITE_TEMPLATE = "website" WEBCLIENT_TEMPLATE = "webclient" +# Whether the webclient "is typing" notification feature is active at all. Set +# to False to disable it completely (server stops responding to typing events +# and the client stays dormant, sending no per-keystroke traffic). +WEBCLIENT_TYPING_ENABLED = True +# Number of seconds for the "typing" notification to timeout. +WEBCLIENT_TYPING_TIMEOUT = 5 +WEBCLIENT_TYPING_AUDIENCE_GETTER = "evennia.server.is_typing.is_typing_get_audience_common_location" # We setup the location of the website template as well as the admin site. TEMPLATES = [ { diff --git a/docs/source/api/evennia.contrib.utils.database_backup.database_backup.md b/docs/source/api/evennia.contrib.utils.database_backup.database_backup.md new file mode 100644 index 0000000000..5ad77b230c --- /dev/null +++ b/docs/source/api/evennia.contrib.utils.database_backup.database_backup.md @@ -0,0 +1,10 @@ +```{eval-rst} +evennia.contrib.utils.database\_backup.database\_backup +============================================================== + +.. automodule:: evennia.contrib.utils.database_backup.database_backup + :members: + :undoc-members: + :show-inheritance: + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.utils.database_backup.md b/docs/source/api/evennia.contrib.utils.database_backup.md new file mode 100644 index 0000000000..4ab7a5e00d --- /dev/null +++ b/docs/source/api/evennia.contrib.utils.database_backup.md @@ -0,0 +1,18 @@ +```{eval-rst} +evennia.contrib.utils.database\_backup +============================================== + +.. automodule:: evennia.contrib.utils.database_backup + :members: + :undoc-members: + :show-inheritance: + + + +.. toctree:: + :maxdepth: 6 + + evennia.contrib.utils.database_backup.database_backup + evennia.contrib.utils.database_backup.tests + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.utils.database_backup.tests.md b/docs/source/api/evennia.contrib.utils.database_backup.tests.md new file mode 100644 index 0000000000..bc0e0042c1 --- /dev/null +++ b/docs/source/api/evennia.contrib.utils.database_backup.tests.md @@ -0,0 +1,10 @@ +```{eval-rst} +evennia.contrib.utils.database\_backup.tests +=================================================== + +.. automodule:: evennia.contrib.utils.database_backup.tests + :members: + :undoc-members: + :show-inheritance: + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.utils.md b/docs/source/api/evennia.contrib.utils.md index b2eb1a6d09..aa772ec402 100644 --- a/docs/source/api/evennia.contrib.utils.md +++ b/docs/source/api/evennia.contrib.utils.md @@ -12,6 +12,7 @@ evennia.contrib.utils :maxdepth: 6 evennia.contrib.utils.auditing + evennia.contrib.utils.database_backup evennia.contrib.utils.debugpy evennia.contrib.utils.fieldfill evennia.contrib.utils.git_integration diff --git a/docs/source/api/evennia.server.is_typing.md b/docs/source/api/evennia.server.is_typing.md new file mode 100644 index 0000000000..47275f69c4 --- /dev/null +++ b/docs/source/api/evennia.server.is_typing.md @@ -0,0 +1,10 @@ +```{eval-rst} +evennia.server.is\_typing +================================ + +.. automodule:: evennia.server.is_typing + :members: + :undoc-members: + :show-inheritance: + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.server.md b/docs/source/api/evennia.server.md index 9d3a18f77c..80bdc4d002 100644 --- a/docs/source/api/evennia.server.md +++ b/docs/source/api/evennia.server.md @@ -18,6 +18,7 @@ evennia.server evennia.server.evennia_launcher evennia.server.initial_setup evennia.server.inputfuncs + evennia.server.is_typing evennia.server.manager evennia.server.models evennia.server.server diff --git a/docs/source/index.md b/docs/source/index.md index 324350dbfe..4cf6944141 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,6 +1,6 @@ # Evennia Documentation -This is the manual of [Evennia](https://www.evennia.com), the open source Python `MU*` creation system. Use the Search bar on the left to find or discover interesting articles. This manual was last updated April 11, 2026, see the [Evennia Changelog](Coding/Changelog.md). Latest released Evennia version is 6.0.0. +This is the manual of [Evennia](https://www.evennia.com), the open source Python `MU*` creation system. Use the Search bar on the left to find or discover interesting articles. This manual was last updated July 05, 2026, see the [Evennia Changelog](Coding/Changelog.md). Latest released Evennia version is 6.1.0. - [Introduction](./Evennia-Introduction.md) - what is this Evennia thing? - [Evennia in Pictures](./Evennia-In-Pictures.md) - a visual overview of Evennia diff --git a/evennia/VERSION.txt b/evennia/VERSION.txt index 09b254e90c..dfda3e0b4f 100644 --- a/evennia/VERSION.txt +++ b/evennia/VERSION.txt @@ -1 +1 @@ -6.0.0 +6.1.0 diff --git a/pyproject.toml b/pyproject.toml index 66f0e19439..ec76ca258c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "evennia" -version = "6.0.0" +version = "6.1.0" maintainers = [{ name = "Griatch", email = "griatch@gmail.com" }] description = "A full-featured toolkit and server for text-based multiplayer games (MUDs, MU*, etc)." requires-python = ">=3.12"