> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shdevelopment.org/llms.txt
> Use this file to discover all available pages before exploring further.

# sh-reports: Player Report System with Discord Logging

> sh-reports lets players submit bug reports, player reports, and suggestions. Logs go to Discord webhooks with optional screenshot capture.

sh-reports gives your players a structured, in-game way to submit Player Reports, Bug Reports, and Suggestions without leaving the server. Opening the `/report` command displays a multi-tab NUI form; when a player submits a report, sh-reports automatically captures a screenshot, formats a Discord embed, and sends everything to the appropriate webhook channel. Admins with the configured ACE permission receive an instant in-game alert so they can respond without monitoring Discord continuously. Role pings, image hosting via Fivemerr, and a server-wide toggle command are all configurable from a single config file.

## Dependencies

| Resource           | Required     | Purpose                                             |
| ------------------ | ------------ | --------------------------------------------------- |
| `screenshot-basic` | **Required** | Captures and attaches screenshots to Discord embeds |
| `sh-notify`        | Recommended  | Default in-game notification handler                |
| Fivemerr account   | Optional     | External image hosting for screenshots              |

<Warning>
  Start `screenshot-basic` **before** `sh-reports` in your `server.cfg`. If `screenshot-basic` is not running when sh-reports loads, no screenshots will be captured and the Discord embeds will be sent without images.
</Warning>

## Installation

<Steps>
  <Step title="Install screenshot-basic">
    Download [screenshot-basic](https://github.com/citizenfx/screenshot-basic) and place it in your `resources` directory. Add `ensure screenshot-basic` to `server.cfg` above sh-reports.
  </Step>

  <Step title="Add sh-reports to your server">
    Place the `sh-reports` folder inside your `resources` directory.

    ```
    resources/
    ├── screenshot-basic/
    ├── sh-notify/
    └── sh-reports/
        ├── fxmanifest.lua
        └── shared/
            └── config.lua
    ```
  </Step>

  <Step title="Configure sh-reports">
    Open `shared/config.lua` and set your Discord webhooks, ACE permission, and any optional features. See the [Configuration](#configuration) section below for the full reference.
  </Step>

  <Step title="Start sh-reports in server.cfg">
    ```cfg server.cfg theme={null}
    ensure screenshot-basic
    ensure sh-notify
    ensure sh-reports
    ```
  </Step>

  <Step title="Add ACE permissions for admins">
    Grant the `admin` ACE permission (or whichever permission you set in `Config.Permission`) to the groups that should receive in-game report alerts.

    ```cfg server.cfg theme={null}
    add_ace group.admin admin allow
    ```
  </Step>
</Steps>

## Configuration

All options are contained in `shared/config.lua`.

```lua shared/config.lua theme={null}
Config.Command  = 'report'              -- Player command to open the report UI

Config.Commands = {
    Report = 'report',                  -- Alias for the report command
    Toggle = 'togglereports',           -- Admin command to disable reports globally
}

Config.Permission = 'admin'             -- ACE permission for in-game admin alerts

Config.Mention = {
    Discord = false,                    -- Ping Discord roles on submission
    InGame  = true,                     -- Alert in-game admins on submission
}

Config.Notify = 'sh'                    -- 'sh' for sh-notify, or 'custom'

Config.EmbedOptions = {
    Color                = 15611494,   -- Discord embed accent colour (decimal format)
    UseFivemerr          = false,      -- Use Fivemerr for image hosting
    fivemerrApiKey       = '',         -- Fivemerr API key if UseFivemerr is true
    PlayerReportWebHook  = '',         -- Discord webhook for player reports
    BugReportWebHook     = '',         -- Discord webhook for bug reports
    SuggestionWebHook    = '',         -- Discord webhook for suggestions
    Storage              = '',         -- Fallback webhook for screenshot hosting
}
```

### General Options

<ParamField path="Config.Command" type="string" default="'report'">
  The chat command players type to open the report UI. Change this to any single word without the leading slash.
</ParamField>

<ParamField path="Config.Commands.Toggle" type="string" default="'togglereports'">
  The admin command that enables or disables the report system server-wide. Admins with the configured ACE permission can run this from the chat or server console.
</ParamField>

<ParamField path="Config.Permission" type="string" default="'admin'">
  The ACE permission node checked to determine who receives in-game report alerts and who can run the toggle command.
</ParamField>

<ParamField path="Config.Notify" type="string" default="'sh'">
  The notification handler used for player-facing messages. Set to `'sh'` to use sh-notify, or `'custom'` if you have integrated your own notification resource.
</ParamField>

### Alert Options

<ParamField path="Config.Mention.Discord" type="boolean" default="false">
  When `true`, sh-reports pings the Discord roles defined in `Config.Roles` each time a report is submitted. Requires valid role IDs and a webhook with permission to mention roles.
</ParamField>

<ParamField path="Config.Mention.InGame" type="boolean" default="true">
  When `true`, all in-game players holding the ACE permission defined in `Config.Permission` receive an instant notification whenever a report is submitted.
</ParamField>

### Webhook and Embed Options

<ParamField path="Config.EmbedOptions.Color" type="number" default="15611494">
  The accent colour of the Discord embed, expressed as a decimal integer. Use a colour converter such as [convertingcolors.com](https://convertingcolors.com/) to convert HEX or RGB values to the decimal format Discord requires.
</ParamField>

<ParamField path="Config.EmbedOptions.PlayerReportWebHook" type="string" required>
  The full Discord webhook URL for Player Report submissions. Each report type sends to its own channel to keep your Discord organised.
</ParamField>

<ParamField path="Config.EmbedOptions.BugReportWebHook" type="string" required>
  The full Discord webhook URL for Bug Report submissions.
</ParamField>

<ParamField path="Config.EmbedOptions.SuggestionWebHook" type="string" required>
  The full Discord webhook URL for Suggestion submissions.
</ParamField>

<ParamField path="Config.EmbedOptions.UseFivemerr" type="boolean" default="false">
  When `true`, screenshots are uploaded to Fivemerr and the hosted URL is embedded in the Discord message. Requires a valid `fivemerrApiKey`.
</ParamField>

<ParamField path="Config.EmbedOptions.fivemerrApiKey" type="string" default="''">
  Your Fivemerr API key. Only required when `UseFivemerr` is set to `true`.
</ParamField>

<ParamField path="Config.EmbedOptions.Storage" type="string" default="''">
  A fallback Discord webhook used to host screenshot attachments when Fivemerr is disabled. Discord's CDN URL from this upload is then embedded in the report webhook message.
</ParamField>

## Discord Role Mentions

When `Config.Mention.Discord` is `true`, sh-reports pings specific Discord roles depending on the report type. Set each role ID to the numeric Discord Role ID for the role you want pinged.

```lua shared/config.lua theme={null}
Config.Roles = {
    PlayerReport = 1234567890,  -- Discord Role ID to ping on player reports
    BugReport    = 1234567890,  -- Discord Role ID to ping on bug reports
}
```

<Note>
  Suggestions do not have a dedicated role ping field. If you want pings for suggestions, assign the same role ID used for `BugReport` or extend the config with a custom entry.
</Note>

## Report Types

sh-reports organises all submissions into three tabs inside the NUI form. Each tab sends to its own configured Discord webhook.

<Accordion title="Player Report">
  Players use this tab to report another player for rule-breaking behaviour. The submitted embed includes the reporter's server ID, the reported player's server ID, a reason field, and an automatic screenshot of the reporter's current view.
</Accordion>

<Accordion title="Bug Report">
  Players use this tab to describe a technical issue or broken feature on the server. The embed includes the reporter's details, a description of the bug, and a screenshot for visual context.
</Accordion>

<Accordion title="Suggestion">
  Players use this tab to submit ideas or feature requests. Suggestions are sent to the dedicated Suggestion webhook without a screenshot by default, keeping that channel free of image clutter.
</Accordion>

## Admin Commands

| Command          | Permission Required     | Description                                                                                                                                                                                   |
| ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/togglereports` | `Config.Permission` ACE | Toggles the entire report system on or off server-wide. Players attempting to submit while reports are disabled receive a notification informing them that reports are currently unavailable. |

<Tip>
  Disable reports temporarily during maintenance windows using `/togglereports` so players are not confused by missing feedback when staff are unavailable to act on submissions.
</Tip>