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

Update the documentation of the event system

Browse source
This commit is contained in:
Vincent Le Goff 2017-04-23 17:02:40 -07:00 • committed by Griatch
parent bc9bfb3fa7
commit 16cbe2c781
8 changed files with 231 additions and 206 deletions
Download patch file Download diff file Expand all files Collapse all files

347
evennia/contrib/events/README.md
View file

@ -6,26 +6,25 @@ This contrib adds the system of events in Evennia, allowing immortals (or other
## A WARNING REGARDING SECURITY
Evennia's event system will run arbitrary Python code without much restriction. Such a system is as powerful as potentially dangerous, and you will have to keep in mind two important questions, and answer them for yourself, before deciding to use this system in your game:
Evennia's event system will run arbitrary Python code without much restriction. Such a system is as powerful as potentially dangerous, and you will have to keep in mind these points before deciding to install it:
1. Is it worth it? This event system isn't some magical feature that would remove the need for the MU*'s development, and empower immortals to create fabulous things without any control. Everything that immortals would be able to do through the event system could be achieved by modifying the source code. Immortals might be familiar with Evennia's design, and could contribute by sending pull requests to your code, for instance. The event system could admittedly earn you time and have immortals adding in special features without the need for complex code. You have to consider, however, if it's worth adding this system in your game. A possible risk is that your immortals will try to do everything though this system and your code will not be updated, while there will still be room to enhance it.
2. Who should use this system? Having arbitrary Python code running cannot be considered a secure feature. You will have to be extremely careful in deciding who can use this system. By default, immortals can create and edit events (these users have access to the `@py` command, which is potentially as dangerous). Builders will not be able to add or edit events, although you can change this setting, to have builders be able to create events, and set their events to require approval by an administrator. You can change permissions (see below for more details on how to do it). You are free to trust or mistrust your builders or other users, just remember that the potential for malign code cannot be restricted.
1. Untrusted people can run Python code on your game server with this system. Be careful about who can use this system (see the permissions below).
2. You can do all of this in Python outside the game. The event system is not to replace all your game feature.
## Basic structure and vocabulary
- At the basis of the event system are **event types**. An **event type** defines the context in which we would like to call some arbitrary code. For instance, one event type is defined on exits and will fire every time a character traverses through this exit. Event types are described on a [typeclass](https://github.com/evennia/evennia/wiki/Typeclasses) (like [exits](https://github.com/evennia/evennia/wiki/Objects#exits) in our example). All objects inheriting from this typeclass will have access to this event type.
- An event type should specify a **trigger**, a simple name describing the moment when the event type will be fired. The event type that will be fired every time a character traverses through an exit is called "traverse". Both "event types" and "trigger" can describe the same thing, although the term **trigger** in the rest of the documentation will be used to describe the moment when the event fires. Users of the system will be more interested in knowing what triggers are available for such and such objects, while developers will be there to create event types.
- Individual events can be set on individual objects. They contain the code that will be executed at a specific moment (when a specific action triggers this event type). More than one event can be connected to an object's event type: for instance, several events can be set on the "traverse" event type of a single exit. They will all be called in the order they have been defined.
- At the basis of the event system are **events**. An **event** defines the context in which we would like to call some arbitrary code. For instance, one event is defined on exits and will fire every time a character traverses through this exit. Events are described on a [typeclass](https://github.com/evennia/evennia/wiki/Typeclasses) (like [exits](https://github.com/evennia/evennia/wiki/Objects#exits) in our example). All objects inheriting from this typeclass will have access to this event.
- **Callbacks** can be set on individual objects, on events defined in code. These **callbacks** can contain arbitrary code and describe a specific behavior for an object. When the event fires, all callbacks connected to this object's event are executed.
To see the system in context, when an object is picked up (using the default `get` command), a specific event type is fired:
To see the system in context, when an object is picked up (using the default `get` command), a specific event is fired:
1. The event type "get" is set on objects (on the `DefaultObject` typeclass).
1. The event "get" is set on objects (on the `Object` typeclass).
2. When using the "get" command to pick up an object, this object's `at_get` hook is called.
3. A modified hook of DefaultObject is set by the event system. This hook will execute (or call) the "get" event type on this object.
4. All events tied to this object's "get" trigger will be executed in order. These events act as functions containing Python code that you can write, using specific variables that will be listed when you edit the event itself.
5. In individual events, you can add multiple lines of Python code that will be fired at this point. In this example, the `character` variable will contain the character who has picked up the object, while `obj` will contain the object that was picked up.
3. A modified hook of DefaultObject is set by the event system. This hook will execute (or call) the "get" event on this object.
4. All callbacks tied to this object's "get" event will be executed in order. These callbacks act as functions containing Python code that you can write in-game, using specific variables that will be listed when you edit the callback itself.
5. In individual callbacks, you can add multiple lines of Python code that will be fired at this point. In this example, the `character` variable will contain the character who has picked up the object, while `obj` will contain the object that was picked up.
Following this example, if you create an event "get" on the object "a sword", and put in it:
Following this example, if you create a callback "get" on the object "a sword", and put in it:
```python
character.msg("You have picked up {} and have completed this quest!".format(obj.get_display_name(character)))
@ -43,11 +42,11 @@ Being in a separate contrib, the event system isn't installed by default. You n
1. Launch the main script:
```@py ev.create_script("evennia.contrib.events.scripts.EventHandler")```
2. Set the permissions (optional):
- `EVENTS_WITH_VALIDATION`: a group that can edit events, but will need approval (default to `None`).
- `EVENTS_WITHOUT_VALIDATION`: a group with permission to edit events without need of validation (default to `"immortals"`).
- `EVENTS_VALIDATING`: a group that can validate events (default to `"immortals"`).
- `EVENTS_CALENDAR`: type of the calendar to be used (either `None`, `"standard"`, `"custom"` or a custom callback, default to `None`).
3. Add the `@event` command.
- `EVENTS_WITH_VALIDATION`: a group that can edit callbacks, but will need approval (default to `None`).
- `EVENTS_WITHOUT_VALIDATION`: a group with permission to edit callbacks without need of validation (default to `"immortals"`).
- `EVENTS_VALIDATING`: a group that can validate callbacks (default to `"immortals"`).
- `EVENTS_CALENDAR`: type of the calendar to be used (either `None`, `"standard"` or `"custom"`, default to `None`).
3. Add the `@call` command.
4. Inherit from the custom typeclasses of the event system.
- `evennia.contrib.events.typeclasses.EventCharacter`: to replace `DefaultCharacter`.
- `evennia.contrib.events.typeclasses.EventExit`: to replace `DefaultExit`.
@ -62,21 +61,19 @@ To start the event script, you only need a single command, using `@py`.
@py ev.create_script("evennia.contrib.events.scripts.EventHandler")
This command will create a global script (that is, a script independent from any object). This script will hold basic configuration, event description and so on. You may access it directly, but you will probably use the custom helper functions (see the section on extending the event system). Doing so will also create a `events` handler on all objects (see below for details).
This command will create a global script (that is, a script independent from any object). This script will hold basic configuration, individual callbacks and so on. You may access it directly, but you will probably use the callback handler. Creating this script will also create a `callback` handler on all objects (see below for details).
### Editing permissions
This contrib comes with its own set of permissions. They define who can edit events without validation, and who can edit events but needs validation. Validation is a process in which an administrator (or somebody trusted as such) will check the events produced by others and will accept or reject them. If accepted, the events are connected, otherwise they are never run.
This contrib comes with its own set of permissions. They define who can edit callbacks without validation, and who can edit callbacks but needs validation. Validation is a process in which an administrator (or somebody trusted as such) will check the callbacks produced by others and will accept or reject them. If accepted, the callbacks are connected, otherwise they are never run.
By default, events can only be created by immortals: no one except the immortals can edit events, and immortals don't need validation. It can easily be changed, either through settings or dynamically by changing permissions of users.
#### Permissions in settings
By default, callbacks can only be created by immortals: no one except the immortals can edit callbacks, and immortals don't need validation. It can easily be changed, either through settings or dynamically by changing permissions of users.
The events contrib adds three [permissions](https://github.com/evennia/evennia/wiki/Locks#permissions) in the settings. You can override them by changing the settings into your `server/conf/settings.py` file (see below for an example). The settings defined in the events contrib are:
- `EVENTS_WITH_VALIDATION`: this defines a permission that can edit events, but will need approval. If you set this to `"wizards"`, for instance, users with the permission `"wizards"` will be able to edit events. These events will not be connected, though, and will need to be checked and approved by an administrator. This setting can contain `None`, meaning that no user is allowed to edit events with validation.
- `EVENTS_WITHOUT_VALIDATION`: this setting defines a permission allowing editing of events without needing validation. By default, this setting is set to `"immortals"`. It means that immortals can edit events, and they will be connected when they leave the editor, without needing approval.
- `EVENTS_VALIDATING`: this last setting defines who can validate events. By default, this is set to `"immortals"`, meaning only immortals can see events needing validation, accept or reject them.
- `EVENTS_WITH_VALIDATION`: this defines a permission that can edit callbacks, but will need approval. If you set this to `"wizards"`, for instance, users with the permission `"wizards"` will be able to edit callbacks. These callbacks will not be connected, though, and will need to be checked and approved by an administrator. This setting can contain `None`, meaning that no user is allowed to edit callbacks with validation.
- `EVENTS_WITHOUT_VALIDATION`: this setting defines a permission allowing editing of callbacks without needing validation. By default, this setting is set to `"immortals"`. It means that immortals can edit callbacks, and they will be connected when they leave the editor, without needing approval.
- `EVENTS_VALIDATING`: this last setting defines who can validate callbacks. By default, this is set to `"immortals"`, meaning only immortals can see callbacks needing validation, accept or reject them.
You can override all these settings in your `server/conf/settings.py` file. For instance:
@ -89,26 +86,17 @@ EVENTS_WITHOUT_VALIDATION = "immortals"
EVENTS_VALIDATING = "immortals"
```
This set of settings means that:
1. Wizards can edit events, but they will need to be individually approved before they are connected. Wizards will be able to add whatever they want, but before their code runs, it will have to be checked and approved by an immortal.
2. Immortals can edit events, their work doesn't need to be approved. It is automatically accepted and connected.
3. Immortals can also see events that need approval (these produced by wizards) and accept or reject them. Whenever accepted, the event is connected and will fire without constraint whenever it has to.
In addition, there is another setting that must be set if you plan on using the time-related events (events that are scheduled at specific, in-game times). You would need to specify the type of calendar you are using. By default, time-related events are disabled. You can change the `EVENTS_CALENDAR` to set it to:
- `"standard"`: the standard calendar, with standard days, months, years and so on.
- `"custom"`: a custom calendar that will use the [custom_gametime](https://github.com/evennia/evennia/blob/master/evennia/contrib/custom_gametime.py) contrib to schedule events.
- A special callback to schedule time-related events in a way not supported by the `gametime` utility and the `custom_gametime` contrib (see below).
#### Permissions on individual users
This contrib defines two additional permissions that can be set on individual users:
- `events_without_validation`: this would give this user the rights to edit events but not require validation before they are connected.
- `events_validating`: this permission allows this user to run validation checks on events needing to be validated.
- `events_without_validation`: this would give this user the rights to edit callbacks but not require validation before they are connected.
- `events_validating`: this permission allows this user to run validation checks on callbacks needing to be validated.
For instance, to give the right to edit events without needing approval to the player 'kaldara', you might do something like:
For instance, to give the right to edit callbacks without needing approval to the player 'kaldara', you might do something like:
@perm *kaldara = events_without_validation
@ -116,15 +104,15 @@ To remove this same permission, just use the `/del` switch:
@perm/del *kaldara = events_without_validation
The rights to use the `@event` command are directly related to these permissions: by default, only users who have the "events_without_validation" permission or are in (or above) the group defined in the `EVENTS_WITH_VALIDATION` setting will be able to call the commands (with different switches).
The rights to use the `@call` command are directly related to these permissions: by default, only users who have the "events_without_validation" permission or are in (or above) the group defined in the `EVENTS_WITH_VALIDATION` setting will be able to call the command (with different switches).
### Adding the `@event` command
### Adding the `@call` command
You also have to add the `@event` command to your Character CmdSet. In your `commands/default_cmdsets`, it might look like this:
You also have to add the `@call` command to your Character CmdSet. This command allows your users to add, edit and delete callbacks in-game. In your `commands/default_cmdsets`, it might look like this:
```python
from evennia import default_cmds
from evennia.contrib.events.commands import CmdEvent
from evennia.contrib.events.commands import CmdCallback
class CharacterCmdSet(default_cmds.CharacterCmdSet):
"""
@ -139,12 +127,12 @@ class CharacterCmdSet(default_cmds.CharacterCmdSet):
Populates the cmdset
"""
super(CharacterCmdSet, self).at_cmdset_creation()
self.add(CmdEvent())
self.add(CmdCallback())
```
### Changing parent classes of typeclasses
Finally, to use the event system, you need to have your typeclasses inherit from the modified event typeclasses. For instance, in your `typeclasses/characters.py` module, you should change inheritance like this:
Finally, to use the event system, you need to have your typeclasses inherit from the modified event classes. For instance, in your `typeclasses/characters.py` module, you should change inheritance like this:
```python
from evennia.contrib.events.typeclasses import EventCharacter
@ -156,23 +144,23 @@ class Character(EventCharacter):
You should do the same thing for your rooms, exits and objects. Note that the event system works by overriding some hooks. Some of these features might not be accessible in your game if you don't call the parent methods when overriding hooks.
## Using the `@event` command
## Using the `@call` command
The event system relies, to a great extent, on its `@event` command. Who can execute this command, and who can do what with it, will depend on your set of permissions.
The event system relies, to a great extent, on its `@call` command. Who can execute this command, and who can do what with it, will depend on your set of permissions.
The event system can be used on most Evennia objects, mostly typeclassed objects (excluding players). The first argument of the `@event` command is the name of the object you want to edit. It can also be used to know what event types are available for this specific object.
The `@call` command allows to add, edit and delete callbacks on specific objects' events. The event system can be used on most Evennia objects, mostly typeclassed objects (excluding players). The first argument of the `@call` command is the name of the object you want to edit. It can also be used to know what events are available for this specific object.
### Examining events and event types
### Examining callbacks and events
To see the event types connected to an object, use the `@event` command and give the name or ID of the object to examine. For instance, @event here` to examine the event types on your current location. Or `@event self` to see the event types on yourself.
To see the events connected to an object, use the `@call` command and give the name or ID of the object to examine. For instance, @call here` to examine the events on your current location. Or `@call self` to see the events on yourself.
This command will display a table, containing:
- The name of each event type (trigger) in the first column.
- The number of events of this name, and the number of total lines of these events in the second column.
- The name of each event in the first column.
- The number of callbacks of this name, and the number of total lines of these callbacks in the second column.
- A short help to tell you when the event is triggered in the third column.
If you execute `@event #1` for instance, you might see a table like this:
If you execute `@call #1` for instance, you might see a table like this:
```
+------------------+---------+-----------------------------------------------+
@ -194,17 +182,17 @@ If you execute `@event #1` for instance, you might see a table like this:
+------------------+---------+-----------------------------------------------+
```
### Creating a new event
### Creating a new callback
The `/add` switch should be used to add an event. It takes two arguments beyond the object's name/DBREF:
The `/add` switch should be used to add a callback. It takes two arguments beyond the object's name/DBREF:
1. After an = sign, the trigger of the event to be edited (if not supplied, will display the list of possible triggers, like above).
1. After an = sign, the name of the event to be edited (if not supplied, will display the list of possible events, like above).
2. The parameters (optional).
We'll see events with parameters later. For the time being, let's try to prevent a character from going through the "north" exit of this room:
We'll see callbacks with parameters later. For the time being, let's try to prevent a character from going through the "north" exit of this room:
```
@event north
@call north
+------------------+---------+-----------------------------------------------+
| Event name | Number | Description |
+~~~~~~~~~~~~~~~~~~+~~~~~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
@ -219,18 +207,18 @@ We'll see events with parameters later. For the time being, let's try to preven
+------------------+---------+-----------------------------------------------+
```
If we want to prevent a character from traversing through this exit, the best trigger for us would be "can_traverse".
If we want to prevent a character from traversing through this exit, the best event for us would be "can_traverse".
> Why not "traverse"? If you read the description of both triggers, you will see "traverse" is called **after** the character has traversed through this exit. It would be too late to prevent it. On the other hand, "can_traverse" is obviously checked before the character traverses.
> Why not "traverse"? If you read the description of both events, you will see "traverse" is called **after** the character has traversed through this exit. It would be too late to prevent it. On the other hand, "can_traverse" is obviously checked before the character traverses.
When we edit the event, we have some more information:
@event/add north = can_traverse
@call/add north = can_traverse
```
Can the character traverse through this exit?
This event is called when a character is about to traverse this
exit. You can use the deny() function to deny the character from
exit. You can use the deny() eventfunc to deny the character from
exiting for this time.
Variables you can use in this event:
@ -239,7 +227,7 @@ Variables you can use in this event:
room: the room in which stands the character before moving.
```
The section dedicated to [helpers](#the-helper-functions) will elaborate on the `deny()` function and other helpers. Let us say, for the time being, that it can prevent an action (in this case, it can prevent the character from traversing through this exit). In the editor that opened when you used `@event/add`, you can type something like:
The section dedicated to [eventfuncs](#the-eventfuncs) will elaborate on the `deny()` function and other eventfuncs. Let us say, for the time being, that it can prevent an action (in this case, it can prevent the character from traversing through this exit). In the editor that opened when you used `@call/add`, you can type something like:
```python
if character.id == 1:
@ -249,12 +237,12 @@ else:
deny()
```
You can now enter `:wq` to leave the editor by saving the event.
You can now enter `:wq` to leave the editor by saving the callback.
If you enter `@event north`, you should see that "can_traverse" now has an active event. You can use `@event north = can_traverse` to see more details on the connected events:
If you enter `@call north`, you should see that "can_traverse" now has an active callback. You can use `@call north = can_traverse` to see more details on the connected callbacks:
```
@event north = can_traverse
@call north = can_traverse
+--------------+--------------+----------------+--------------+--------------+
| Number | Author | Updated | Param | Valid |
+~~~~~~~~~~~~~~+~~~~~~~~~~~~~~+~~~~~~~~~~~~~~~~+~~~~~~~~~~~~~~+~~~~~~~~~~~~~~+
@ -262,15 +250,15 @@ If you enter `@event north`, you should see that "can_traverse" now has an activ
+--------------+--------------+----------------+--------------+--------------+
```
The left column contains event numbers. You can use them to have even more information on a specific event. Here, for instance:
The left column contains callback numbers. You can use them to have even more information on a specific event. Here, for instance:
```
@event north = can_traverse 1
Event can_traverse 1 of north:
@call north = can_traverse 1
Callback can_traverse 1 of north:
Created by XXXXX on 2017-04-02 17:58:05.
Updated by XXXXX on 2017-04-02 18:02:50
This event is connected and active.
Event code:
This callback is connected and active.
Callback code:
if character.id == 1:
character.msg("You're the superuser, 'course I'll let you pass.")
else:
@ -280,30 +268,30 @@ else:
Then try to walk through this exit. Do it with another character if possible, too, to see the difference.
### Editing and removing an event
### Editing and removing a callback
You can use the `/edit` switch to the `@event` command to edit an event. You should provide, after the name of the object to edit and the equal sign:
You can use the `/edit` switch to the `@call` command to edit a callback. You should provide, after the name of the object to edit and the equal sign:
1. The name of the event (as seen above).
2. A number, if several events are connected at this location.
2. A number, if several callbacks are connected at this location.
You can type `@event/edit <object> = <event_name>` to see the events that are linked at this location. If there is only one event, it will be opened in the editor; if more are defined, you will be asked for a number to provide (for instance, `@event/edit north = can_traverse 2`).
You can type `@call/edit <object> = <event name>` to see the callbacks that are linked at this location. If there is only one callback, it will be opened in the editor; if more are defined, you will be asked for a number to provide (for instance, `@call/edit north = can_traverse 2`).
The command `@event` also provides a `/del` switch to remove an event. It takes the same arguments as the `/edit` switch.
The command `@call` also provides a `/del` switch to remove a callback. It takes the same arguments as the `/edit` switch.
When removed, events are logged, so an administrator can retrieve its content, assuming the `/del` was an error.
When removed, callbacks are logged, so an administrator can retrieve its content, assuming the `/del` was an error.
### The code editor
When adding or editing an event, the event editor should open in code mode. The additional options supported by the editor in this mode are describe in [a dedicated section of the EvEditor's documentation](https://github.com/evennia/evennia/wiki/EvEditor#the-eveditor-to-edit-code).
When adding or editing a callback, the event editor should open in code mode. The additional options supported by the editor in this mode are describe in [a dedicated section of the EvEditor's documentation](https://github.com/evennia/evennia/wiki/EvEditor#the-eveditor-to-edit-code).
## Using events
The following sections describe how to use events for various tasks, from the most simple to the most complex.
### The helper functions
### The eventfuncs
In order to make development a little easier, the event system provides helper functions to be used in events themselves. You don't have to use them, they are just shortcuts.
In order to make development a little easier, the event system provides eventfuncs to be used in callbacks themselves. You don't have to use them, they are just shortcuts. An eventfunc is just a simple function that can be used inside of your callback code.
Function | Argument | Description | Example
-----------|--------------------------|-----------------------------------|--------
@ -313,29 +301,29 @@ call_event | `(obj, name, seconds=0)` | Call another event. | `cal
#### deny
The `deny()` function allows to interrupt the event and the action that called it. In the `can_*` events, it can be used to prevent the action from happening. For instance, in `can_say` on rooms, it can prevent the character from saying something in the room. One could have a `can_eat` event set on food that would prevent this character from eating this food.
The `deny()` function allows to interrupt the callback and the action that called it. In the `can_*` events, it can be used to prevent the action from happening. For instance, in `can_say` on rooms, it can prevent the character from saying something in the room. One could have a `can_eat` event set on food that would prevent this character from eating this food.
Behind the scenes, the `deny()` function raises an exception that is being intercepted by the handler of events. The handler will then report that the action was cancelled.
#### get
The `get` helper is a shortcut to get a single object with a specific identity. It's often used to retrieve an object with a given ID. In the section dedicated to [chained events](#chained-events), you will see a concrete example of this helper in action.
The `get` eventfunc is a shortcut to get a single object with a specific identity. It's often used to retrieve an object with a given ID. In the section dedicated to [chained events](#chained-events), you will see a concrete example of this function in action.
#### call_event
Some events will call others. It is particularly useful for [chained events](#chained-events) that are described in a dedicated section. This helper is used to call another event, immediately or in a defined time.
Some callbacks will call other events. It is particularly useful for [chained events](#chained-events) that are described in a dedicated section. This eventfunc is used to call another event, immediately or in a defined time.
You need to specify as first parameter the object containing the event. The second parameter is the name of the event to call. The third parameter is the number of seconds before calling this event. By default, this parameter is set to 0 (the event is called immediately).
### Variables in events
### Variables in callbacks
In the Python code you will enter in individual events, you will have access to variable in your locals. These variables will depend on the event, and will be clearly listed when you add or edit it. As you've seen in the previous example, when we manipulate characters or character actions, we often have a `character` variable that holds the character doing the action.
In the Python code you will enter in individual callbacks, you will have access to variables in your locals. These variables will depend on the event, and will be clearly listed when you add or edit a callback. As you've seen in the previous example, when we manipulate characters or character actions, we often have a `character` variable that holds the character doing the action.
In most cases, when an event type is fired, all events from this event type are called. Variables are created for each event. Sometimes, however, the event type will execute and then ask for a variable in your event: in other words, some events can alter the actions being performed by changing values of variables. This is always clearly specified in the help of the event.
In most cases, when an event is fired, all callbacks from this event are called. Variables are created for each event. Sometimes, however, the callback will execute and then ask for a variable in your locals: in other words, some callbacks can alter the actions being performed by changing values of variables. This is always clearly specified in the help of the event.
One example that will illustrate this system is the event type "msg_leave" that can be set on exits. This event can alter the message that will be sent to other characters when someone leave through this exit.
One example that will illustrate this system is the "msg_leave" event that can be set on exits. This event can alter the message that will be sent to other characters when someone leaves through this exit.
@event/add down = msg_leave
@call/add down = msg_leave
Which should display:
@ -373,30 +361,32 @@ And if the character Wilfred takes this exit, others in the room will see:
Wildred falls into a hole in the ground!
In this case, the event system placed the variable "message" in the event, but will read from it when the event has been executed.
In this case, the event system placed the variable "message" in the callback locals, but will read from it when the event has been executed.
### Events with parameters
### Callbacks with parameters
Some events are called without parameter. It has been the case for all examples we have seen before. In some cases, you can create events that are triggered under only some conditions. A typical example is the room's "say" event. This event is triggered when somebody says something in the room. The event can be configured to fire only when some words are used in the sentence.
Some callbacks are called without parameter. It has been the case for all examples we have seen before. In some cases, you can create callbacks that are triggered under only some conditions. A typical example is the room's "say" event. This event is triggered when somebody says something in the room. Individual callbacks set on this event can be configured to fire only when some words are used in the sentence.
For instance, let's say we want to create a cool voice-operated elevator. You enter into the elevator and say the floor number... and the elevator moves in the right direction. In this case, we could create an event with the parameter "one":
For instance, let's say we want to create a cool voice-operated elevator. You enter into the elevator and say the floor number... and the elevator moves in the right direction. In this case, we could create an callback with the parameter "one":
@event/add here = say one
@call/add here = say one
This event will only fire when the user says a sentence that contains "one".
This callback will only fire when the user says a sentence that contains "one".
But what if we want to have an event that would fire if the user says 1 or one? We can provide several parameters, separated by a comma.
But what if we want to have a callback that would fire if the user says 1 or one? We can provide several parameters, separated by a comma.
@event/add here = say 1, one
@call/add here = say 1, one
Or, still more keywords:
@event/add here = say 1, one, ground
@call/add here = say 1, one, ground
This time, the user could say something like "take me to the ground floor" ("ground" is one of our keywords defined in the above event).
This time, the user could say something like "take me to the ground floor" ("ground" is one of our keywords defined in the above callback).
Not all events can take parameters, and these who do have different ways of handling them. There isn't a single meaning to parameters that could apply to all events. Refer to the event documentation for details.
> If you get confused between callback variables and parameters, think of parameters as checks performed before the callback is run. Event with parameters will only fire some specific callbacks, not all of them.
### Time-related events
Events are usually linked to commands, as we saw before. However, this is not always the case. Events can be triggered by other actions and, as we'll see later, could even be called from inside other events!
@ -406,7 +396,7 @@ There is a specific event, on all objects, that can trigger at a specific time.
For instance, let's add an event on this room that should trigger every day, at precisely 12:00 PM (the time is given as game time, not real time):
```
@event here = time 12:00
@call here = time 12:00
```
```python
@ -414,7 +404,7 @@ For instance, let's add an event on this room that should trigger every day, at
room.msg_contents("It's noon, time to have lunch!")
```
Now, at noon every MUD day, this event will fire. You can use this event on every kind of typeclassed object, to have a specific action done every MUD day at the same time.
Now, at noon every MUD day, this event will fire and this callback will be executed. You can use this event on every kind of typeclassed object, to have a specific action done every MUD day at the same time.
Time-related events can be much more complex than this. They can trigger every in-game hour or more often (it might not be a good idea to have events trigger that often on a lot of objects). You can have events that run every in-game week or month or year. It will greatly vary depending on the type of calendar used in your game. The number of time units is described in the game configuration.
@ -433,9 +423,9 @@ Notice that we specify units in the reverse order (year, month, day, hour and mi
### Chained events
Events can call other events, either now or a bit later. It is potentially very powerful.
Callbacks can call other events, either now or a bit later. It is potentially very powerful.
To use chained events, just use the `call_event` helper function. It takes 2-3 arguments:
To use chained events, just use the `call_event` eventfunc. It takes 2-3 arguments:
- The object containing the event.
- The name of the event to call.
@ -443,23 +433,22 @@ To use chained events, just use the `call_event` helper function. It takes 2-3
All objects have events that are not triggered by commands or game-related operations. They are called "chain_X", like "chain_1", "chain_2", "chain_3" and so on. You can give them more specific names, as long as it begins by "chain_", like "chain_flood_room".
Rather than a long explanation, let's look at an example: a subway that will go from one place to the next at regular times. Creating exits (opening its doors), waiting a bit, closing them, rolling around and stopping at a different station. That's quite a complex set of events, as it is, but let's only look at the part that opens and closes the doors:
Rather than a long explanation, let's look at an example: a subway that will go from one place to the next at regular times. Connecting exits (opening its doors), waiting a bit, closing them, rolling around and stopping at a different station. That's quite a complex set of callbacks, as it is, but let's only look at the part that opens and closes the doors:
@event/add here = time 10:00
@call/add here = time 10:00
```python
# At 10:00 AM, the subway arrives in the room of ID 22.
# Notice that exit #23 and #24 are respectively the exit leading
# on the platform and back in the subway.
station = get(id=22)
# Open the door
to_exit = get(id=23)
back_exit = get(id=24)
# Open the door
to_exit.name = "platform"
to_exit.aliases = ["p"]
to_exit.location = room
to_exit.destination = station
# Create the return exit
back_exit = get(id=24)
back_exit.name = "subway"
back_exit.location = station
back_exit.destination = room
@ -470,16 +459,16 @@ station.msg_contents("The doors of the subway open with a dull clank.")
call_event(room, "chain_1", 20)
```
This event will:
This callback will:
1. Be called at 10:00 AM (specify 22:00 to say 10:00 PM).
1. Be called at 10:00 AM (specify 22:00 to set it to 10:00 PM).
2. Set an exit between the subway and the station. Notice that the exits already exist (you will not have to create them), but they don't need to have specific location and destination.
3. Display a message both in the subway and on the platform.
4. Call the event "chain_1" to execute in 20 seconds.
And now, what should we have in "chain_1"?
@event/add here = chain_1
@call/add here = chain_1
```python
# Close the doors
@ -493,71 +482,69 @@ station.msg_content("After a short warning signal, the doors close and the subwa
Behind the scenes, the `call_event` function freezes all variables ("room", "station", "to_exit", "back_exit" in our example), so you don't need to define them again.
A word of caution on events that call chained events: it isn't impossible for an event to call itself at some recursion level. If `chain_1` calls `chain_2` that calls `chain_3` that calls `chain_`, particularly if there's no pause between them, you might run into an infinite loop.
A word of caution on callbacks that call chained events: it isn't impossible for a callback to call itself at some recursion level. If `chain_1` calls `chain_2` that calls `chain_3` that calls `chain_`, particularly if there's no pause between them, you might run into an infinite loop.
Be also careful when it comes to handling characters or objects that may very well move during your pause between event calls. When you use `call_event()`, the MUD doesn't pause and commands can be entered by players, fortunately. It also means that, a character could start an event that pauses for awhile, but be gone when the chained event is called. You need to check that, even lock the character into place while you are pausing (some actions should require locking) or at least, checking that the character is still in the room, for it might create illogical situations if you don't.
> Chained events are a special case: contrary to standard events, they are created in-game, not through code. They usually contain only one callback, although nothing prevents you from creating several chained events in the same object.
## Using events in code
This section describes events and event types from code, how to create new event types, how to call them in a command, and how to handle specific cases like parameters.
This section describes callbacks and events from code, how to create new events, how to call them in a command, and how to handle specific cases like parameters.
Along this section, we will see how to implement the following example: we would like to create a "push" command that could be used to push objects. Objects could react to this and have specific events fired.
Along this section, we will see how to implement the following example: we would like to create a "push" command that could be used to push objects. Objects could react to this command and have specific events fired.
### Adding new event types
### Adding new events
Adding new event types should be done below your typeclasses. For instance, if you want to add a new event type on all your rooms, you should probably edit your `typeclasses/rooms.py` module. We'll see how to add a "push" event type to all objeects. To add a new event type, you should use the `create_event_type` function defined in `evennia.contrib.events.custom`. This function takes 4 arguments.
Adding new events should be done in your typeclasses. Events are contained in the `_events` class variable, a dictionary of event names as keys, and tuples to describe these events as values. You also need to register this class, to tell the event system that it contains events to be added to this typeclass.
- The class to have these events (defined above).
- The trigger of the event type to add (str).
- The list of variables to be present when calling this events (list of str).
- The help text of this event (str).
The variables define what will be accessible in the namespace of your event. Here, when we "push" an object, we would like to know what object is pushed, and who has pushed it (we'll limit this command to characters). You can edit `typeclasses/objects.py` to modify/add the following lines:
Here, we want to add a "push" event on objects. In your `typeclasses/objects.py` file, you should write something like:
```python
from evennia.contrib.events.custom import create_event_type, connect_event_types
from evennia.contrib.events.utils import register_events
from evennia.contrib.events.typeclasses import EventObject
EVENT_PUSH = """
A character push the object.
This event is called when a character uses the "push" command on
an object in the same room.
Variables you can use in this event:
character: the character that pushes this object.
obj: the object connected to this event.
"""
@register_events
class Object(EventObject):
# ...
"""
Class representing objects.
"""
# Object events
create_event_type(Object, "push", ["character", "obj"], """
A character push the object.
This event is called when a character uses the "push" command on
an object in the same room.
Variables you can use in this event:
character: the character that pushes this object.
obj: the object connected to this event.
""")
# Force-update the new event types
connect_event_types()
_events = {
"push": (["character", "obj"], EVENT_PUSH),
}
```
Here we have set:
- Line 1-2: we import several things we will need from the event system. Note that we use `EventObject` as a parent instead of `DefaultObject`, as explained in the installation.
- Line 4-12: we usually define the help of the event in a separate variable, this is more readable, though there's no rule against doing it another way. Usually, the help should contain a short explanation on a single line, a longer explanation on several lines, and then the list of variables with explanations.
- Line 14: we call a decorator on the class to indicate it contains events. If you're not familiar with decorators, you don't really have to worry about it, just remember to put this line just above the class definition if your class contains events.
- Line 15: we create the class inheriting from `EventObject`.
- Line 20-22: we define the events of our objects in an `_events` class variable. It is a dictionary. Keys are event names. Values are a tuple containing:
- The list of variable names (list of str). This will determine what variables are needed when the event triggers. These variables will be used in callbacks (as we'll see below).
- The event help (a str, the one we have defined above).
1. The typeclass (here, `Object`), meaning that this event will be accessible to all instances of `Object` or a child class.
2. `"push"` as the trigger (the name of the event type).
3. Two variables ("character" and "obj") that will be accessible in our event namespace.
4. A longer help text to describe more in details when this event will fire. It's best to keep this format as much as possible: a single line to briefly describe the event, a longer explanation on several lines, and the list of variables of this event.
> It's best to call `connect_event_types()` after having defined new event types. It can be kept for the very last line of the file. The event system doesn't automatically integrate new event types, this function is to force it to do so.
If you save this code and reload your game, you should see the new event type if you enter the `@event` command with an object as argument.
If you add this code and reload your game, create an object and examine its events with `@call`, you should see the "push" event with its help. Of course, right now, the event exists, but it's not fired.
### Calling an event in code
The event system is accessible through a handler on all objects. This handler is named `events` and can be accessed from any typeclassed object (your character, a room, an exit...). This handler offers several methods to examine and call an event type on this object.
The event system is accessible through a handler on all objects. This handler is named `callbacks` and can be accessed from any typeclassed object (your character, a room, an exit...). This handler offers several methods to examine and call an event or callback on this object.
To call an event, use the `events.call` method in an object. It takes as argument:
To call an event, use the `callbacks.call` method in an object. It takes as argument:
- The name of the event type to call.
- All variables that will be accessible in the event as positional arguments. They should be specified in the order chosen when [creating new event types](#adding-new-event-types).
- The name of the event to call.
- All variables that will be accessible in the event as positional arguments. They should be specified in the order chosen when [creating new events](#adding-new-events).
Following the same example, so far, we have created an event type on all objects, called "push". This event type is never fired for the time being. We could add a "push" command, taking as argument the name of an object. If this object is valid, it will call its "push" event type.
Following the same example, so far, we have created an event on all objects, called "push". This event is never fired for the time being. We could add a "push" command, taking as argument the name of an object. If this object is valid, it will call its "push" event.
```python
from commands.command import Command
@ -589,27 +576,27 @@ class CmdPush(Command):
self.msg("You push {}.".format(obj.get_display_name(self.caller)))
# Call the "push" event type of this object
obj.events.call("push", self.caller, obj)
# Call the "push" event of this object
obj.callbacks.call("push", self.caller, obj)
```
Here we use `events.call` with the following arguments:
Here we use `callbacks.call` with the following arguments:
- `"push"`: the name of the event type to be called.
- `"push"`: the name of the event to be called.
- `self.caller`: the one who pushed the button (this is our first variable, `character`).
- `obj`: the object being pushed (our second variable, `obj`).
In the "push" event of our objects, we then can use the "character" variable (containing the one who pushed the object), and the "obj" variable (containing the object that was pushed).
In the "push" callbacks of our objects, we then can use the "character" variable (containing the one who pushed the object), and the "obj" variable (containing the object that was pushed).
### See it all work
To see the effect of the two modifications above (the added event type and the "push" command), let us create a simple object:
To see the effect of the two modifications above (the added event and the "push" command), let us create a simple object:
@create/drop rock
@desc rock = It's a single rock, apparently pretty heavy. Perhaps you can try to push it though.
@event/add rock = push
@call/add rock = push
In the event you could write:
In the callback you could write:
```python
from random import randint
@ -621,26 +608,58 @@ if number == 6:
You can now try to "push rock". You'll try to push the rock, and once out of six times, you will see a message about a "beautiful ant-hill".
### Adding new helper functions
### Adding new eventfuncs
Helper functions, like `deny(), are defined in `contrib/events/helpers.py`. You can add your own helpers by creating a file named `event_helpers.py` in your `world` directory. The functions defined in this file will be added as helpers.
Eventfuncs, like `deny(), are defined in `contrib/events/eventfuncs.py`. You can add your own eventfuncs by creating a file named `eventfuncs.py` in your `world` directory. The functions defined in this file will be added as helpers.
You can also decide to create your helper functions in another location, or even in several locations. To do so, edit the `EVENTS_HELPERS_LOCATIONS` setting in your `server/conf/settings.py` file, specifying either a python path or a list of Python paths in which your helper functions are defined. For instance:
You can also decide to create your eventfuncs in another location, or even in several locations. To do so, edit the `EVENTFUNCS_LOCATION` setting in your `server/conf/settings.py` file, specifying either a python path or a list of Python paths in which your helper functions are defined. For instance:
```python
EVENTS_HELPERS_LOCATIONS = [
"world.events.helpers",
EVENTFUNCS_LOCATIONS = [
"world.events.functions",
]
```
### Creating events with parameters
If you want to create events with parameters (if you create a "whisper" or "ask" command, for instance, and need to have some characters automatically react to words), you can set an additional argument in the tuple of events in your typeclass' `_events` class variable. This third argument must contain a callback that will be called to filter through the list of callbacks when the event fires. Two types of parameters are commonly used (but you can define more parameter types, although this is out of the scope of this documentation).
- Keyword parameters: callbacks of this event will be filtered based on specific keywords. This is useful if you want the user to specify a word and compare this word to a list.
- Phrase parameters: callbacks will be filtered using an entire phrase and checking all its words. The "say" command uses phrase parameters (you can set a "say" callback to fires if a phrase contains one specific word).
In both cases, you need to import a function from `evennia.contrib.events.utils` and use it as third parameter in your event definition.
- `keyword_event` should be used for keyword parameters.
- `phrase_event` should be used for phrase parameters.
For example, here is the definition of the "say" event:
```python
from evennia.contrib.events.utils import register_events, phrase_event
# ...
@register_events
class SomeTypeclass:
_events = {
"say": (["speaker", "character", "message"], CHARACTER_SAY, phrase_event),
}
```
When you call an event using the `obj.callbacks.call` method, you should also provide the parameter, using the `parameters` keyword:
```python
obj.callbacks.call(..., parameters="<put parameters here>")
```
It is necessary to specifically call the event with parameters, otherwise the system will not be able to know how to filter down the list of callbacks.
## Disabling all events at once
When events are running in an infinite loop, for instance, or sending unwanted information to players or other sources, you, as the game administrator, have the power to restart without events. The best way to do this is to use a custom setting, in your setting file (`server/conf/settings.py`):
When callbacks are running in an infinite loop, for instance, or sending unwanted information to players or other sources, you, as the game administrator, have the power to restart without events. The best way to do this is to use a custom setting, in your setting file (`server/conf/settings.py`):
```python
# Disable all events
EVENTS_DISABLED = True
```
The event system will still be accessible (you will have access to the `@event` command, to debug), but no event will be called automatically.
The event system will still be accessible (you will have access to the `@call` command, to debug), but no event will be called automatically.

2
evennia/contrib/events/handler.py → evennia/contrib/events/callbackhandler.py
View file

@ -1,5 +1,5 @@
"""
Module containing the EventHandler for individual objects.
Module containing the CallbackHandler for individual objects.
"""
from collections import namedtuple

8
evennia/contrib/events/commands.py
View file

@ -58,7 +58,7 @@ You can also add a number after the callback name to see details on one callback
@call here = say 2
You can also add, edit or remove callbacks using the add, edit or del switches.
Additionally, you can see the list of differed tasks created by callbacks
(chained callbacks to be called) using the /tasks switch.
(chained events to be called) using the /tasks switch.
"""
VALIDATOR_TEXT = """
@ -264,7 +264,7 @@ class CmdCallback(COMMAND_DEFAULT_CLASS):
number = len(callbacks.get(name, []))
lines = sum(len(e["code"].splitlines()) for e in callbacks.get(name, []))
no = "{} ({})".format(number, lines)
description = types.get(name, (None, "Chained callback."))[1]
description = types.get(name, (None, "Chained event."))[1]
description = description.strip("\n").splitlines()[0]
table.add_row(name, no, description)
@ -282,7 +282,7 @@ class CmdCallback(COMMAND_DEFAULT_CLASS):
"typeclass {}.".format(callback_name, obj, type(obj)))
return
definition = types.get(callback_name, (None, "Chained callback"))
definition = types.get(callback_name, (None, "Chained event."))
description = definition[1]
self.msg(raw(description.strip("\n")))
@ -352,7 +352,7 @@ class CmdCallback(COMMAND_DEFAULT_CLASS):
self.handler.db.locked.append((obj, callback_name, number))
# Check the definition of the callback
definition = types.get(callback_name, (None, "Chained callback"))
definition = types.get(callback_name, (None, "Chained event."))
description = definition[1]
self.msg(raw(description.strip("\n")))

58
evennia/contrib/events/eventfuncs.py
View file

@ -12,11 +12,12 @@ def deny():
"""
Deny, that is stop, the event here.
This function will raise an exception to terminate the event
in a controlled way. If you use this function in an event called
prior to a command, the command will be cancelled as well. Good
situations to use the `deny()` function are in events that begins
by `can_`, because they usually can be cancelled as easily as that.
Notes:
This function will raise an exception to terminate the event
in a controlled way. If you use this function in an event called
prior to a command, the command will be cancelled as well. Good
situations to use the `deny()` function are in events that begins
by `can_`, because they usually can be cancelled as easily as that.
"""
raise InterruptEvent
@ -25,17 +26,6 @@ def get(**kwargs):
"""
Return an object with the given search option or None if None is found.
This function is very useful to retrieve objects with a specific
ID. You know that room #32 exists, but you don't have it in
the event variables. Quite simple:
room = get(id=32)
This function doesn't perform a search on objects, but a direct
search in the database. It's recommended to use it for objects
you know exist, using their IDs or other unique attributes.
Looking for objects by key is possible (use `db_key` as an
argument) but remember several objects can share the same key.
Kwargs:
Any searchable data or property (id, db_key, db_location...).
@ -43,6 +33,18 @@ def get(**kwargs):
The object found that meet these criteria for research, or
None if none is found.
Notes:
This function is very useful to retrieve objects with a specific
ID. You know that room #32 exists, but you don't have it in
the callback variables. Quite simple:
room = get(id=32)
This function doesn't perform a search on objects, but a direct
search in the database. It's recommended to use it for objects
you know exist, using their IDs or other unique attributes.
Looking for objects by key is possible (use `db_key` as an
argument) but remember several objects can share the same key.
"""
try:
object = ObjectDB.objects.get(**kwargs)
@ -55,32 +57,32 @@ def call_event(obj, event_name, seconds=0):
"""
Call the specified event in X seconds.
This helper can be used to call other events from inside of an event
in a given time. This will create a pause between events. This
will not freeze the game, and you can expect characters to move
around (unless you prevent them from doing so).
Variables that are accessible in your event using 'call()' will be
kept and passed on to the event to call.
Args:
obj (Object): the typeclassed object containing the event.
event_name (str): the event name to be called.
seconds (int or float): the number of seconds to wait before calling
the event.
Note:
Chained events are designed for this very purpose: they
Notes:
This eventfunc can be used to call other events from inside of an
event in a given time. This will create a pause between events. This
will not freeze the game, and you can expect characters to move
around (unless you prevent them from doing so).
Variables that are accessible in your event using 'call()' will be
kept and passed on to the event to call.
Chained callbacks are designed for this very purpose: they
are never called automatically by the game, rather, they need
to be called from inside another event.
"""
script = type(obj.events).script
script = type(obj.callbacks).script
if script:
# If seconds is 0, call the event immediately
if seconds == 0:
locals = dict(script.ndb.current_locals)
obj.events.call(event_name, locals=locals)
obj.callbacks.call(event_name, locals=locals)
else:
# Schedule the task
script.set_task(seconds, obj, event_name)

2
evennia/contrib/events/scripts.py
View file

@ -14,7 +14,7 @@ from evennia import logger
from evennia.utils.create import create_channel
from evennia.utils.dbserialize import dbserialize
from evennia.utils.utils import all_from_module, delay
from evennia.contrib.events.handler import CallbackHandler
from evennia.contrib.events.callbackhandler import CallbackHandler
from evennia.contrib.events.utils import get_next_wait, EVENTS, InterruptEvent
# Constants

2
evennia/contrib/events/tests.py
View file

@ -13,7 +13,7 @@ from evennia.utils import ansi, utils
from evennia.utils.create import create_object, create_script
from evennia.utils.test_resources import EvenniaTest
from evennia.contrib.events.commands import CmdCallback
from evennia.contrib.events.handler import CallbackHandler
from evennia.contrib.events.callbackhandler import CallbackHandler
# Force settings
settings.EVENTS_CALENDAR = "standard"

7
evennia/contrib/events/typeclasses.py
View file

@ -9,8 +9,8 @@ EventRoom, EventCharacter and EventExit).
from evennia import DefaultCharacter, DefaultExit, DefaultObject, DefaultRoom
from evennia import ScriptDB
from evennia.utils.utils import delay, inherits_from, lazy_property
from evennia.contrib.events.callbackhandler import CallbackHandler
from evennia.contrib.events.utils import register_events, time_event, phrase_event
from evennia.contrib.events.handler import CallbackHandler
# Character help
CHARACTER_CAN_DELETE = """
@ -28,7 +28,7 @@ CHARACTER_CAN_MOVE = """
Can the character move?
This event is called before the character moves into another
location. You can prevent the character from moving
using the 'deny()' function.
using the 'deny()' eventfunc.
Variables you can use in this event:
character: the character connected to this event.
@ -782,6 +782,9 @@ class EventRoom(DefaultRoom):
speaker (Object): The object speaking.
message (str): The words spoken.
Returns:
The message to be said (str) or None.
Notes:
You should not need to add things like 'you say: ' or
similar here, that should be handled by the say command before

11
evennia/contrib/events/utils.py
View file

@ -90,15 +90,16 @@ def get_next_wait(format):
Args:
format (str): a time format matching the set calendar.
The time format could be something like "2018-01-08 12:00". The
number of units set in the calendar affects the way seconds are
calculated.
Returns:
until (int or float): the number of seconds until the event.
usual (int or float): the usual number of seconds between events.
format (str): a string format representing the time.
Notes:
The time format could be something like "2018-01-08 12:00". The
number of units set in the calendar affects the way seconds are
calculated.
"""
calendar = getattr(settings, "EVENTS_CALENDAR", None)
if calendar is None:
@ -157,7 +158,7 @@ def time_event(obj, event_name, number, parameters):
Create a time-related event.
Args:
obj (Object): the object on which stands the event.
obj (Object): the object on which sits the event.
event_name (str): the event's name.
number (int): the number of the event.
parameters (str): the parameter of the event.