<p>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.</p>
<p>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.</p>
<sectionid="installation">
<h2>Installation<aclass="headerlink"href="#installation"title="Permalink to this headline">¶</a></h2>
<p>To install the reports contrib, just add the provided cmdset to your default AccountCmdSet:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in commands/default_cmdset.py</span>
<p>The contrib also has two optional settings: <codeclass="docutils literal notranslate"><spanclass="pre">INGAME_REPORT_TYPES</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">INGAME_REPORT_STATUS_TAGS</span></code>.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">INGAME_REPORT_TYPES</span></code> setting is covered in detail in the section “Adding new types of reports”.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">INGAME_REPORT_STATUS_TAGS</span></code> setting is covered in the section “Managing reports”.</p>
</section>
<sectionid="usage">
<h2>Usage<aclass="headerlink"href="#usage"title="Permalink to this headline">¶</a></h2>
<p>By default, the following report types are available:</p>
<ulclass="simple">
<li><p>Bugs: Report bugs encountered during gameplay.</p></li>
<li><p>Ideas: Submit suggestions for game improvement.</p></li>
<li><p>Players: Report inappropriate player behavior.</p></li>
</ul>
<p>Players can submit new reports through the command for each report type, and staff are given access to a report-management command and menu.</p>
<sectionid="submitting-reports">
<h3>Submitting reports<aclass="headerlink"href="#submitting-reports"title="Permalink to this headline">¶</a></h3>
<p>Players can submit reports using the following commands:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">bug</span><spanclass="pre"><text></span></code> - Files a bug report. An optional target can be included - <codeclass="docutils literal notranslate"><spanclass="pre">bug</span><spanclass="pre"><target></span><spanclass="pre">=</span><spanclass="pre"><text></span></code> - making it easier for devs/builders to track down issues.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">report</span><spanclass="pre"><player></span><spanclass="pre">=</span><spanclass="pre"><text></span></code> - Reports a player for inappropriate or rule-breaking behavior. <em>Requires</em> a target to be provided - it searches among accounts by default.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">idea</span><spanclass="pre"><text></span></code> - Submits a general suggestion, with no target. It also has an alias of <codeclass="docutils literal notranslate"><spanclass="pre">ideas</span></code> which allows you to view all of your submitted ideas.</p></li>
</ul>
</section>
<sectionid="managing-reports">
<h3>Managing reports<aclass="headerlink"href="#managing-reports"title="Permalink to this headline">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">manage</span><spanclass="pre">reports</span></code> command allows staff to review and manage the various types of reports by launching a management menu.</p>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">manage</span><spanclass="pre"><report</span><spanclass="pre">type>s</span></code> - by default, this means it makes <codeclass="docutils literal notranslate"><spanclass="pre">manage</span><spanclass="pre">bugs</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">manage</span><spanclass="pre">players</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">manage</span><spanclass="pre">ideas</span></code> available along with the default <codeclass="docutils literal notranslate"><spanclass="pre">manage</span><spanclass="pre">reports</span></code>, and that e.g. <codeclass="docutils literal notranslate"><spanclass="pre">manage</span><spanclass="pre">bugs</span></code> will launch the management menu for <codeclass="docutils literal notranslate"><spanclass="pre">bug</span></code>-type reports.</p>
<p>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: <codeclass="docutils literal notranslate"><spanclass="pre">in</span><spanclass="pre">progress</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">closed</span></code>.</p>
<blockquote>
<div><p>Note: A report is created with no status tags, which is considered “open”</p>
</div></blockquote>
<p>If you want a different set of statuses for your reports, you can define the <codeclass="docutils literal notranslate"><spanclass="pre">INGAME_REPORT_STATUS_TAGS</span></code> to your list of statuses.</p>
<p><strong>Example</strong></p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in server/conf/settings.py</span>
<spanclass="c1"># this will allow for the statuses of 'in progress', 'rejected', and 'completed', without the contrib-default of 'closed'</span>
<h3>Adding new types of reports<aclass="headerlink"href="#adding-new-types-of-reports"title="Permalink to this headline">¶</a></h3>
<p>The contrib is designed to make adding new types of reports to the system as simple as possible, requiring only two steps:</p>
<olclass="simple">
<li><p>Update your settings file to include an <codeclass="docutils literal notranslate"><spanclass="pre">INGAME_REPORT_TYPES</span></code> setting.</p></li>
<li><p>Create and add a new <codeclass="docutils literal notranslate"><spanclass="pre">ReportCmd</span></code> to your command set.</p></li>
</ol>
<sectionid="update-your-settings">
<h4>Update your settings<aclass="headerlink"href="#update-your-settings"title="Permalink to this headline">¶</a></h4>
<p>The contrib optionally references <codeclass="docutils literal notranslate"><spanclass="pre">INGAME_REPORT_TYPES</span></code> in your <codeclass="docutils literal notranslate"><spanclass="pre">settings.py</span></code> 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.</p>
<p>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.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in server/conf/settings.py</span>
<spanclass="c1"># this redefines the setting to not include 'ideas', so the ideas command and reports won't be available</span>
<h4>Create a new ReportCmd<aclass="headerlink"href="#create-a-new-reportcmd"title="Permalink to this headline">¶</a></h4>
<p><codeclass="docutils literal notranslate"><spanclass="pre">ReportCmdBase</span></code> 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.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> - 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.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">report_type</span></code> - The type of report this command is for (e.g. <codeclass="docutils literal notranslate"><spanclass="pre">player</span></code>). You only need to set it if you want a different string from the key.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">report_locks</span></code> - The locks you want applied to the created reports. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">"read:pperm(Admin)"</span></code></p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">success_msg</span></code> - The string which is sent to players after submitting a report of this type. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">"Your</span><spanclass="pre">report</span><spanclass="pre">has</span><spanclass="pre">been</span><spanclass="pre">filed."</span></code></p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">require_target</span></code>: Set to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> if your report type requires a target (e.g. player reports).</p></li>
</ul>
<blockquote>
<div><p>Note: The contrib’s own commands - <codeclass="docutils literal notranslate"><spanclass="pre">CmdBug</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">CmdIdea</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">CmdReport</span></code> - are implemented the same way, so you can review them as examples.</p>
<spanclass="n">success_message</span><spanclass="o">=</span><spanclass="s2">"You have successfully filed a custom report."</span>
</pre></div>
</div>
<p>Add this new command to your default cmdset to enable filing your new report type.</p>
<hrclass="docutils"/>
<p><small>This document page is generated from <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/base_systems/ingame_reports/README.md</span></code>. Changes to this
file will be overwritten, so edit that file rather than this one.</small></p>
