diff --git a/CHANGELOG.md b/CHANGELOG.md index a2d8c84dd2..33b9f5531d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md index a2d8c84dd2..33b9f5531d 100644 --- a/docs/source/Coding/Changelog.md +++ b/docs/source/Coding/Changelog.md @@ -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 diff --git a/docs/source/Contribs/Contrib-Ingame-Reports.md b/docs/source/Contribs/Contrib-Ingame-Reports.md new file mode 100644 index 0000000000..20157af3f9 --- /dev/null +++ b/docs/source/Contribs/Contrib-Ingame-Reports.md @@ -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 ` - Files a bug report. An optional target can be included - `bug = ` - making it easier for devs/builders to track down issues. +* `report = ` - Reports a player for inappropriate or rule-breaking behavior. *Requires* a target to be provided - it searches among accounts by default. +* `idea ` - 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 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 + + 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. + + +---- + +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. diff --git a/docs/source/Contribs/Contribs-Overview.md b/docs/source/Contribs/Contribs-Overview.md index 49f0e4f431..f19fb61548 100644 --- a/docs/source/Contribs/Contribs-Overview.md +++ b/docs/source/Contribs/Contribs-Overview.md @@ -7,7 +7,7 @@ in the [Community Contribs & Snippets][forum] forum. _Contribs_ are optional code snippets and systems contributed by the Evennia community. They vary in size and complexity and may be more specific about game types and styles than 'core' Evennia. -This page is auto-generated and summarizes all **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._ diff --git a/docs/source/api/evennia.contrib.base_systems.ingame_reports.md b/docs/source/api/evennia.contrib.base_systems.ingame_reports.md new file mode 100644 index 0000000000..c7d130792c --- /dev/null +++ b/docs/source/api/evennia.contrib.base_systems.ingame_reports.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.base_systems.ingame_reports.menu.md b/docs/source/api/evennia.contrib.base_systems.ingame_reports.menu.md new file mode 100644 index 0000000000..e253b05d69 --- /dev/null +++ b/docs/source/api/evennia.contrib.base_systems.ingame_reports.menu.md @@ -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: + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.base_systems.ingame_reports.reports.md b/docs/source/api/evennia.contrib.base_systems.ingame_reports.reports.md new file mode 100644 index 0000000000..acdcee38f5 --- /dev/null +++ b/docs/source/api/evennia.contrib.base_systems.ingame_reports.reports.md @@ -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: + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.base_systems.ingame_reports.tests.md b/docs/source/api/evennia.contrib.base_systems.ingame_reports.tests.md new file mode 100644 index 0000000000..3cb42bee82 --- /dev/null +++ b/docs/source/api/evennia.contrib.base_systems.ingame_reports.tests.md @@ -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: + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.base_systems.md b/docs/source/api/evennia.contrib.base_systems.md index 3b8409adcf..781ff3f24b 100644 --- a/docs/source/api/evennia.contrib.base_systems.md +++ b/docs/source/api/evennia.contrib.base_systems.md @@ -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 diff --git a/docs/source/index.md b/docs/source/index.md index 6c5e318fd0..6d561adbf3 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,6 +1,6 @@ # Evennia Documentation -This is the manual of [Evennia](https://www.evennia.com), the open source Python `MU*` creation system. Use the Search bar on the left to find or discover interesting articles. This manual was last updated 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 diff --git a/evennia/contrib/base_systems/ingame_reports/README.md b/evennia/contrib/base_systems/ingame_reports/README.md index 0fdbfab737..00c1cbf905 100644 --- a/evennia/contrib/base_systems/ingame_reports/README.md +++ b/evennia/contrib/base_systems/ingame_reports/README.md @@ -1,5 +1,7 @@ # 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. @@ -116,7 +118,7 @@ class CmdCustomReport(ReportCmdBase): Usage: customreport - + This is a custom report type. """ @@ -125,4 +127,4 @@ class CmdCustomReport(ReportCmdBase): success_message = "You have successfully filed a custom report." ``` -Add this new command to your default cmdset to enable filing your new report type. \ No newline at end of file +Add this new command to your default cmdset to enable filing your new report type.