mirror of
https://github.com/evennia/evennia.git
synced 2026-03-16 21:06:30 +01:00
Update docs, add contrib header for new repor system contrib
This commit is contained in:
Griatch
parent
096100ee55
commit
783dc46cd3
11 changed files with 215 additions and 9 deletions
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
## Main
|
||||
|
||||
- [Feat][pull3531]: New contrib; `in-game reports` for handling user reportgs,
|
||||
bugs etc in-game (InspectorCaracal)
|
||||
- [Feat][pull3586]: Add ANSI color support `|U`, `|I`, `|i`, `|s`, `|S` for
|
||||
underline reset, italic/reset and strikethrough/reset (0xDEADFED5)
|
||||
- [Fix][pull3550]: Issue where rpsystem contrib search would do a global instead
|
||||
|
|
@ -18,6 +20,7 @@ underline reset, italic/reset and strikethrough/reset (0xDEADFED5)
|
|||
[pull3571]: https://github.com/evennia/evennia/pull/3571
|
||||
[pull3586]: https://github.com/evennia/evennia/pull/3586
|
||||
[pull3550]: https://github.com/evennia/evennia/pull/3550
|
||||
[pull3531]: https://github.com/evennia/evennia/pull/3531
|
||||
|
||||
## Evennia 4.2.0
|
||||
|
||||
|
|
|
|||
136
docs/source/Contribs/Contrib-Ingame-Reports.md
Normal file
136
docs/source/Contribs/Contrib-Ingame-Reports.md
Normal file
|
|
@ -0,0 +1,136 @@
|
|||
# In-Game Reporting System
|
||||
|
||||
Contrib by InspectorCaracal, 2024
|
||||
|
||||
This contrib provides an in-game reports system, handling bug reports, player reports, and idea submissions by default. It also supports adding your own types of reports, or removing any of the default report types.
|
||||
|
||||
Each type of report has its own command for submitting new reports, and an admin command is also provided for managing the reports through a menu.
|
||||
|
||||
## Installation
|
||||
|
||||
To install the reports contrib, just add the provided cmdset to your default AccountCmdSet:
|
||||
|
||||
```python
|
||||
# in commands/default_cmdset.py
|
||||
|
||||
from evennia.contrib.base_systems.ingame_reports import ReportsCmdSet
|
||||
|
||||
class AccountCmdSet(default_cmds.AccountCmdSet):
|
||||
# ...
|
||||
|
||||
def at_cmdset_creation(self):
|
||||
# ...
|
||||
self.add(ReportsCmdSet)
|
||||
```
|
||||
|
||||
The contrib also has two optional settings: `INGAME_REPORT_TYPES` and `INGAME_REPORT_STATUS_TAGS`.
|
||||
|
||||
The `INGAME_REPORT_TYPES` setting is covered in detail in the section "Adding new types of reports".
|
||||
|
||||
The `INGAME_REPORT_STATUS_TAGS` setting is covered in the section "Managing reports".
|
||||
|
||||
## Usage
|
||||
|
||||
By default, the following report types are available:
|
||||
|
||||
* Bugs: Report bugs encountered during gameplay.
|
||||
* Ideas: Submit suggestions for game improvement.
|
||||
* Players: Report inappropriate player behavior.
|
||||
|
||||
Players can submit new reports through the command for each report type, and staff are given access to a report-management command and menu.
|
||||
|
||||
### Submitting reports
|
||||
|
||||
Players can submit reports using the following commands:
|
||||
|
||||
* `bug <text>` - Files a bug report. An optional target can be included - `bug <target> = <text>` - making it easier for devs/builders to track down issues.
|
||||
* `report <player> = <text>` - Reports a player for inappropriate or rule-breaking behavior. *Requires* a target to be provided - it searches among accounts by default.
|
||||
* `idea <text>` - Submits a general suggestion, with no target. It also has an alias of `ideas` which allows you to view all of your submitted ideas.
|
||||
|
||||
### Managing reports
|
||||
|
||||
The `manage reports` command allows staff to review and manage the various types of reports by launching a management menu.
|
||||
|
||||
This command will dynamically add aliases to itself based on the types of reports available, with each command string launching a menu for that particular report type. The aliases are built on the pattern `manage <report type>s` - by default, this means it makes `manage bugs`, `manage players`, and `manage ideas` available along with the default `manage reports`, and that e.g. `manage bugs` will launch the management menu for `bug`-type reports.
|
||||
|
||||
Aside from reading over existing reports, the menu allows you to change the status of any given report. By default, the contrib includes two different status tags: `in progress` and `closed`.
|
||||
|
||||
> Note: A report is created with no status tags, which is considered "open"
|
||||
|
||||
If you want a different set of statuses for your reports, you can define the `INGAME_REPORT_STATUS_TAGS` to your list of statuses.
|
||||
|
||||
**Example**
|
||||
|
||||
```python
|
||||
# in server/conf/settings.py
|
||||
|
||||
# this will allow for the statuses of 'in progress', 'rejected', and 'completed', without the contrib-default of 'closed'
|
||||
INGAME_REPORT_STATUS_TAGS = ('in progress', 'rejected', 'completed')
|
||||
```
|
||||
|
||||
### Adding new types of reports
|
||||
|
||||
The contrib is designed to make adding new types of reports to the system as simple as possible, requiring only two steps:
|
||||
|
||||
1. Update your settings file to include an `INGAME_REPORT_TYPES` setting.
|
||||
2. Create and add a new `ReportCmd` to your command set.
|
||||
|
||||
#### Update your settings
|
||||
|
||||
The contrib optionally references `INGAME_REPORT_TYPES` in your settings.py to see which types of reports can be managed. If you want to change the available report types, you'll need to define this setting.
|
||||
|
||||
```python
|
||||
# in server/conf/settings.py
|
||||
|
||||
# this will include the contrib's report types as well as a custom 'complaint' report type
|
||||
INGAME_REPORT_TYPES = ('bugs', 'ideas', 'players', 'complaints')
|
||||
```
|
||||
|
||||
You can also use this setting to remove any of the contrib's report types - the contrib will respect this setting when building its cmdset with no additional steps.
|
||||
|
||||
```python
|
||||
# in server/conf/settings.py
|
||||
|
||||
# this redefines the setting to not include 'ideas', so the ideas command and reports won't be available
|
||||
INGAME_REPORT_TYPES = ('bugs', 'players')
|
||||
```
|
||||
|
||||
#### Create a new ReportCmd
|
||||
|
||||
`ReportCmdBase` is a parent command class which comes with the main functionality for submitting reports. Creating a new reporting command is as simple as inheriting from this class and defining a couple of class attributes.
|
||||
|
||||
* `key` - This is the same as for any other command, setting the command's usable key. It also acts as the report type if that isn't explicitly set.
|
||||
* `report_type` - The type of report this command is for (e.g. `player`). You only need to set it if you want a different string from the key.
|
||||
* `report_locks` - The locks you want applied to the created reports. Defaults to `"read:pperm(Admin)"`
|
||||
* `success_msg` - The string which is sent to players after submitting a report of this type. Defaults to `"Your report has been filed."`
|
||||
* `require_target`: Set to `True` if your report type requires a target (e.g. player reports).
|
||||
|
||||
> Note: The contrib's own commands - `CmdBug`, `CmdIdea`, and `CmdReport` - are implemented the same way, so you can review them as examples.
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
from evennia.contrib.base_systems.ingame_reports.reports import ReportCmdBase
|
||||
|
||||
class CmdCustomReport(ReportCmdBase):
|
||||
"""
|
||||
file a custom report
|
||||
|
||||
Usage:
|
||||
customreport <message>
|
||||
|
||||
This is a custom report type.
|
||||
"""
|
||||
|
||||
key = "customreport"
|
||||
report_type = "custom"
|
||||
success_message = "You have successfully filed a custom report."
|
||||
```
|
||||
|
||||
Add this new command to your default cmdset to enable filing your new report type.
|
||||
|
||||
|
||||
----
|
||||
|
||||
<small>This document page is generated from `evennia/contrib/base_systems/ingame_reports/README.md`. Changes to this
|
||||
file will be overwritten, so edit that file rather than this one.</small>
|
||||
|
|
@ -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 **50** contribs currently included
|
||||
This page is auto-generated and summarizes all **51** contribs currently included
|
||||
with the Evennia distribution.
|
||||
|
||||
All contrib categories are imported from `evennia.contrib`, such as
|
||||
|
|
@ -34,11 +34,12 @@ If you want to add a contrib, see [the contrib guidelines](./Contribs-Guidelines
|
|||
| [color_markups](#color_markups) | [components](#components) | [containers](#containers) | [cooldowns](#cooldowns) | [crafting](#crafting) |
|
||||
| [custom_gametime](#custom_gametime) | [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) | [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) | [talking_npc](#talking_npc) | [traits](#traits) | [tree_select](#tree_select) |
|
||||
| [turnbattle](#turnbattle) | [tutorial_world](#tutorial_world) | [unixcommand](#unixcommand) | [wilderness](#wilderness) | [xyzgrid](#xyzgrid) |
|
||||
| [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) | [talking_npc](#talking_npc) | [traits](#traits) |
|
||||
| [tree_select](#tree_select) | [turnbattle](#turnbattle) | [tutorial_world](#tutorial_world) | [unixcommand](#unixcommand) | [wilderness](#wilderness) |
|
||||
| [xyzgrid](#xyzgrid) |
|
||||
|
||||
|
||||
|
||||
|
|
@ -64,6 +65,7 @@ Contrib-Custom-Gametime.md
|
|||
Contrib-Email-Login.md
|
||||
Contrib-Godotwebsocket.md
|
||||
Contrib-Ingame-Python.md
|
||||
Contrib-Ingame-Reports.md
|
||||
Contrib-Menu-Login.md
|
||||
Contrib-Mux-Comms-Cmds.md
|
||||
Contrib-Unixcommand.md
|
||||
|
|
@ -173,6 +175,16 @@ this module carefully before continuing.
|
|||
|
||||
|
||||
|
||||
### `ingame_reports`
|
||||
|
||||
_Contrib by InspectorCaracal, 2024_
|
||||
|
||||
This contrib provides an in-game reports system, handling bug reports, player reports, and idea submissions by default. It also supports adding your own types of reports, or removing any of the default report types.
|
||||
|
||||
[Read the documentation](./Contrib-Ingame-Reports.md) - [Browse the Code](evennia.contrib.base_systems.ingame_reports)
|
||||
|
||||
|
||||
|
||||
### `menu_login`
|
||||
|
||||
_Contribution by Vincent-lg 2016. Reworked for modern EvMenu by Griatch, 2019._
|
||||
|
|
|
|||
|
|
@ -0,0 +1,19 @@
|
|||
```{eval-rst}
|
||||
evennia.contrib.base\_systems.ingame\_reports
|
||||
=====================================================
|
||||
|
||||
.. automodule:: evennia.contrib.base_systems.ingame_reports
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 6
|
||||
|
||||
evennia.contrib.base_systems.ingame_reports.menu
|
||||
evennia.contrib.base_systems.ingame_reports.reports
|
||||
evennia.contrib.base_systems.ingame_reports.tests
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
```{eval-rst}
|
||||
evennia.contrib.base\_systems.ingame\_reports.menu
|
||||
=========================================================
|
||||
|
||||
.. automodule:: evennia.contrib.base_systems.ingame_reports.menu
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
```{eval-rst}
|
||||
evennia.contrib.base\_systems.ingame\_reports.reports
|
||||
============================================================
|
||||
|
||||
.. automodule:: evennia.contrib.base_systems.ingame_reports.reports
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
```{eval-rst}
|
||||
evennia.contrib.base\_systems.ingame\_reports.tests
|
||||
==========================================================
|
||||
|
||||
.. automodule:: evennia.contrib.base_systems.ingame_reports.tests
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
```
|
||||
|
|
@ -19,6 +19,7 @@ evennia.contrib.base\_systems
|
|||
evennia.contrib.base_systems.email_login
|
||||
evennia.contrib.base_systems.godotwebsocket
|
||||
evennia.contrib.base_systems.ingame_python
|
||||
evennia.contrib.base_systems.ingame_reports
|
||||
evennia.contrib.base_systems.menu_login
|
||||
evennia.contrib.base_systems.mux_comms_cmds
|
||||
evennia.contrib.base_systems.unixcommand
|
||||
|
|
|
|||
|
|
@ -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 July 10, 2024, see the [Evennia Changelog](Coding/Changelog.md). Latest released Evennia version is 4.2.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 13, 2024, see the [Evennia Changelog](Coding/Changelog.md). Latest released Evennia version is 4.2.0.
|
||||
|
||||
- [Introduction](./Evennia-Introduction.md) - what is this Evennia thing?
|
||||
- [Evennia in Pictures](./Evennia-In-Pictures.md) - a visual overview of Evennia
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue