Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-16 21:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fix at_server_reload_start not firing. Resolve #3477. Add Server-Lifecycle.md docpage

Browse source
This commit is contained in:
Griatch 2024-04-06 14:08:36 +02:00
parent 50d8ae2f54
commit 387533d1f0
15 changed files with 222 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/source/Coding/Changelog.md
View file

@ -1,5 +1,34 @@
# Changelog
## Main branch
- [Fix][pull3438]: Error with 'you' mapping in third-person style of
`msg_contents` (InspectorCaracal)
- [Fix][pull3472]: The new `filter_visible` didn't exclude oneself by default
(InspectorCaracal)
- Fix: `find #dbref` results didn't include the results of
`.get_extra_display_name_info` (the #dbref display by default) (Griatch)
- Fix: Add `DefaultAccount.get_extra_display_name_info` method for API
compliance with `DefaultObject` in commands. (Griatch)
- Fix: Show `XYZRoom` subclass when repr() it. (Griatch)
- [Fix][pull3485]: Typo in `sethome` message (chiizujin)
- [Fix][pull3487]: Fix traceback when using `get`,`drop` and `give` with no
arguments (InspectorCaracal)
- [Fix][issue3476]: Don't ignore EvEditor commands with wrong capitalization
(Griatch)
- [Fix][issue3477]: The `at_server_reload_start()` hook was not firing on
a reload (regression).
- [Docs] Added new [Server-Lifecycle][doc-server-lifecycle] page to describe
the hooks called on server start/stop/reload (Griatch)
[pull3438]: https://github.com/evennia/evennia/pull/3446
[pull3485]: https://github.com/evennia/evennia/pull/3485
[pull3487]: https://github.com/evennia/evennia/pull/3487
[issue3476]: https://github.com/evennia/evennia/issues/3476
[issue3477]: https://github.com/evennia/evennia/issues/3477
[doc-server-lifecycle]: https://www.evennia.com/docs/latest/Concepts/Server-Lifecycle.html
## Evennia 4.1.0
April 1, 2024
@ -49,7 +78,8 @@ April 1, 2024
differentiating from their lower-case alternatives (Griatch)
- [Fix][issue3460]: The `menu_login` contrib regression caused it to error out
when creating a new character (Griatch)
- Doc: Added Beginner Tutorial lessons for AI, Quests and Procedural dungeon (Griatch)
- Doc: Added Beginner Tutorial lessons for [Monster and NPC AI][docAI],
[Quests][docQuests] and [Making a Procedural dungeon][docDungeon] (Griatch)
- Doc fixes (Griatch, InspectorCaracal, homeofpoe)
[pull3421]: https://github.com/evennia/evennia/pull/3421
@ -70,6 +100,9 @@ April 1, 2024
[issue3462]: https://github.com/evennia/evennia/issues/3462
[issue3460]: https://github.com/evennia/evennia/issues/3460
[issue3461]: https://github.com/evennia/evennia/issues/3461
[docAI]: https://www.evennia.com/docs/latest/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-AI.html
[docQuests]: https://www.evennia.com/docs/latest/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Quests.html
[docDungeon]: https://www.evennia.com/docs/latest/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Dungeon.html
## Evennia 4.0.0

1
docs/source/Concepts/Concepts-Overview.md
View file

@ -37,6 +37,7 @@ Banning.md
```{toctree}
:maxdepth: 2
Server-Lifecycle
Protocols.md
Models.md
Zones.md

81
docs/source/Concepts/Server-Lifecycle.md Normal file
View file

@ -0,0 +1,81 @@
# Evennia Server Lifecycle
As part of your game design you may want to change how Evennia behaves when starting or stopping. A common use case would be to start up some piece of custom code you want to always have available once the server is up.
Evennia has three main life cycles, all of which you can add custom behavior for:
- **Database life cycle**: Evennia runs on top of one several [supported databases](../Setup/Choosing-a-Database.md). It's possible to wipe this database to 'start over' without needing to separately download Evennia anew.
- **Reboot life cycle**: From When Evennia starts from zero, to it being fully shut down, which means both Portal and Server are stopped. This kicks all players.
- **Reload life cycle:** This is the main runtime, until a "reload" event. Reloads do not kick any players.
## When Evennia first starts
This is the beginning of the **Database life cycle**, just after the database is created and migrated for the first time. After that it won't run again unless you wipe the database and initialize a new one (see [Choosing a Database](../Setup/Choosing-a-Database.md)).
Hooks called, in sequence:
1. `evennia.server.initial_setup.handle_setup(last_step=None)`: Evennia's core initialization function. This is what creates the #1 Character (tied to the superuser) and Limbo. It calls the next hook below and also understands to restart at the last failed step if there was some issue. You should normally not override this function unless you _really_ know what you are doing, but in that case you'd do so by setting `settings.INITIAL_SETUP_MODULE` to your own module with a `handle_setup` function in it.
2. `mygame/server/conf/at_initial_setup.py` contains a single function, `at_initial_setup()`, which will be called without arguments. It's called last in the setup sequence by the above function. Use this to add your own custom behavior or to tweak the initialization. If you for example wanted to change the auto-generated Limbo room, you should do it from here. If you want to change where this function is found, you can do so by changing `settings.AT_INITIAL_SETUP_HOOK_MODULE`.
## When Evennia starts and shutdowns
This is the **Reboot life cycle**. Evennia consists of two main processes, the [Portal and the Server](../Components/Portal-And-Server.md). On a reboot or shutdown, both Portal and Server shuts down, which means all players are disconnected.
Each process call a series of hooks located in `mygame/server/conf/at_server_startstop.py`. You can customize the module used with `settings.AT_SERVER_STARTSTOP_MODULE` - this can even be a list of modules, if so, the appropriately-named functions will be called from each module, in sequence.
All hooks are called without arguments.
> The use of the term 'server' in the hook-names indicate the whole of Evennia, not just the `Server` component.
### Server cold start
Starting the server from zero, after a full stop. This is done with `evennia start` from the terminal.
1. `at_server_init()` - Always called first in the startup sequence.
2. `at_server_cold_start()` - Only called on cold starts.
3. `at_server_start()` - Always called last in the startup sequece.
### Server cold shutdown
Shutting everything down. Done with `shutdown` in-game or `evennia stop` from the terminal.
1. `at_server_cold_stop()` - Only called on cold stops.
2. `at_server_stop()` - Always called last in the stopping sequence.
### Server reboots
This is done with `evennia reboot` and effectively constitutes an automatic cold shutdown followed by a cold start controlled from the `evennia` launcher. There are no special `reboot` hooks for this, instead it looks like you'd expect:
1. `at_server_cold_stop()`
2. `at_server_stop()` (after this, both `Server` + `Portal` have both shut down)
3. `at_server_init()` (like a cold start)
4. `at_server_cold_start()`
5. `at_server_start()`
## When Evennia reloads and resets
This is the **Reload life cycle**. As mentioned above, Evennia consists of two components, the [Portal and Server](../Components/Portal-And-Server.md). During a reload, only the `Server` component is shut down and restarted. Since the Portal stays up, players are not disconnected.
All hooks are called without arguments.
### Server reload
Reloads are initiated with the `reload` command in-game, or with `evennia reload` from the terminal.
1. `at_server_reload_stop()` - Only called on reload stops.
2. `at_server_stop` - Always called last in the stopping sequence.
3. `at_server_init()` - Always called first in startup sequence.
4. `at_server_reload_start()` - Only called on a reload (re)start.
5. `at_server_start()` - Always called last in the startup sequence.
### Server reset
A 'reset' is a hybrid reload state, where the reload is treated as a cold shutdown only for the sake of running hooks (players are not disconnected). It's run with `reset` in-game or with `evennia reset` from the terminal.
1. `at_server_cold_stop()`
2. `at_server_stop()` (after this, only `Server` has shut down)
3. `at_server_init()` (`Server` coming back up)
4. `at_server_cold_start()`
5. `at_server_start()`

52
docs/source/Setup/Settings.md
View file

@ -1,7 +1,6 @@
# Changing Game Settings
Evennia runs out of the box without any changes to its settings. But there are several important
ways to customize the server and expand it with your own plugins.
Evennia runs out of the box without any changes to its settings. But there are several important ways to customize the server and expand it with your own plugins.
All game-specific settings are located in the `mygame/server/conf/` directory.
@ -17,13 +16,9 @@ heavily documented and up-to-date, so you should refer to this file directly for
Since `mygame/server/conf/settings.py` is a normal Python module, it simply imports
`evennia/settings_default.py` into itself at the top.
This means that if any setting you want to change were to depend on some *other* default setting,
you might need to copy & paste both in order to change them and get the effect you want (for most
commonly changed settings, this is not something you need to worry about).
This means that if any setting you want to change were to depend on some *other* default setting, you might need to copy & paste both in order to change them and get the effect you want (for most commonly changed settings, this is not something you need to worry about).
You should never edit `evennia/settings_default.py`. Rather you should copy&paste the select
variables you want to change into your `settings.py` and edit them there. This will overload the
previously imported defaults.
You should never edit `evennia/settings_default.py`. Rather you should copy&paste the select variables you want to change into your `settings.py` and edit them there. This will overload the previously imported defaults.
```{warning} Don't copy everything!
It may be tempting to copy *everything* from `settings_default.py` into your own settings file just to have it all in one place. Don't do this. By copying only what you need, you can easier track what you changed.
@ -41,45 +36,24 @@ In code, the settings is accessed through
Each setting appears as a property on the imported `settings` object. You can also explore all possible options with `evennia.settings_full` (this also includes advanced Django defaults that are not touched in default Evennia).
> When importing `settings` into your code like this, it will be *read
only*. You *cannot* edit your settings from your code! The only way to change an Evennia setting is
to edit `mygame/server/conf/settings.py` directly. You will also need to restart the server
(possibly also the Portal) before a changed setting becomes available.
> When importing `settings` into your code like this, it will be *read only*. You *cannot* edit your settings from your code! The only way to change an Evennia setting is to edit `mygame/server/conf/settings.py` directly. You will also need to restart the server (possibly also the Portal) before a changed setting becomes available.
## Other files in the `server/conf` directory
Apart from the main `settings.py` file,
- `at_initial_setup.py` - this allows you to add a custom startup method to be called (only) the
very first time Evennia starts (at the same time as user #1 and Limbo is created). It can be made to
start your own global scripts or set up other system/world-related things your game needs to have
running from the start.
- `at_server_startstop.py` - this module contains two functions that Evennia will call every time
the Server starts and stops respectively - this includes stopping due to reloading and resetting as
well as shutting down completely. It's a useful place to put custom startup code for handlers and
other things that must run in your game but which has no database persistence.
- `connection_screens.py` - all global string variables in this module are interpreted by Evennia as
a greeting screen to show when an Account first connects. If more than one string variable is
present in the module a random one will be picked.
- `at_initial_setup.py` - this allows you to add a custom startup method to be called (only) the very first time Evennia starts (at the same time as user #1 and Limbo is created). It can be made to start your own global scripts or set up other system/world-related things your game needs to have running from the start.
- `at_server_startstop.py` - this module contains functions that Evennia will call every time the Server starts and stops respectively - this includes stopping due to reloading and resetting as well as shutting down completely. It's a useful place to put custom startup code for handlers and other things that must run in your game but which has no database persistence.
- `connection_screens.py` - all global string variables in this module are interpreted by Evennia as a greeting screen to show when an Account first connects. If more than one string variable is present in the module a random one will be picked.
- `inlinefuncs.py` - this is where you can define custom [FuncParser functions](../Components/FuncParser.md).
- `inputfuncs.py` - this is where you define custom [Input functions](../Components/Inputfuncs.md) to handle data
from the client.
- `lockfuncs.py` - this is one of many possible modules to hold your own "safe" *lock functions* to
make available to Evennia's [Locks](../Components/Locks.md).
- `mssp.py` - this holds meta information about your game. It is used by MUD search engines (which
you often have to register with) in order to display what kind of game you are running along with
statistics such as number of online accounts and online status.
- `inputfuncs.py` - this is where you define custom [Input functions](../Components/Inputfuncs.md) to handle data from the client.
- `lockfuncs.py` - this is one of many possible modules to hold your own "safe" *lock functions* to make available to Evennia's [Locks](../Components/Locks.md).
- `mssp.py` - this holds meta information about your game. It is used by MUD search engines (which you often have to register with) in order to display what kind of game you are running along with statistics such as number of online accounts and online status.
- `oobfuncs.py` - in here you can define custom [OOB functions](../Concepts/OOB.md).
- `portal_services_plugin.py` - this allows for adding your own custom services/protocols to the
Portal. It must define one particular function that will be called by Evennia at startup. There can
be any number of service plugin modules, all will be imported and used if defined. More info can be
found [here](https://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols).
- `server_services_plugin.py` - this is equivalent to the previous one, but used for adding new
services to the Server instead. More info can be found
[here](https://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols).
- `portal_services_plugin.py` - this allows for adding your own custom services/protocols to the Portal. It must define one particular function that will be called by Evennia at startup. There can be any number of service plugin modules, all will be imported and used if defined. More info can be found [here](https://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols).
- `server_services_plugin.py` - this is equivalent to the previous one, but used for adding new services to the Server instead. More info can be found [here](https://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols).
Some other Evennia systems can be customized by plugin modules but has no explicit template in
`conf/`:
Some other Evennia systems can be customized by plugin modules but has no explicit template in `conf/`:
- *cmdparser.py* - a custom module can be used to totally replace Evennia's default command parser. All this does is to split the incoming string into "command name" and "the rest". It also handles things like error messages for no-matches and multiple-matches among other things that makes this more complex than it sounds. The default parser is *very* generic, so you are most often best served by modifying things further down the line (on the command parse level) than here.
- *at_search.py* - this allows for replacing the way Evennia handles search results. It allows to change how errors are echoed and how multi-matches are resolved and reported (like how the default understands that "2-ball" should match the second "ball" object if there are two of them in the room).