Regear System Documentation

The Regear System allows your guild to open structured regear tickets, route them to staff, track ticket states, and keep an audit trail with logs and optional transcriptions.

Table of Contents

• System Overview
• Prerequisites
• Dashboard Setup (Regear System)
• Activation Checklist
• Request Flow (End User)
• Buttons and Interactions
• Data Model
• Logs and Transcription
• Troubleshooting

System Overview

The Regear System has three layers working together:

• Dashboard configuration: defines channels, roles, categories, embed text, role icons, and feature flags.
• Discord interactions: handles ticket creation and ticket actions through buttons, select menu, and modals.
• Database persistence: stores configuration and each request lifecycle event.

Main actors

• Requester: opens regular/special regear ticket from embed.
• Staff: role defined in config, can complete or deny requests.
• Manager/Admin: configures and maintains the system in dashboard.

Prerequisites

• Server setup completed with /setup start.
• Bot present in guild with permission to create channels and manage permission overwrites.
• At least one category for regular and/or special requests.
• Staff role configured in Regear System.
• A text channel selected to publish the request embed.

Dashboard Setup (Regear System)

Open dashboard -> select guild -> click Regear System in sidebar.

Basic Settings

• Embed Channel: where the public regear embed is posted.
• Regear Log Channel: channel for regear activity logs.
• Transcription Channel: where closed ticket transcriptions are posted.
• Staff Role (Can Complete Regears): role allowed to complete/deny.

Embed Customization

• Embed Title / Description / Color for public request message.
• Embed image and request example image are supported.

Category and access mapping

• Regular Regear Categories: possible parent categories for regular tickets.
• Special Regear Categories: possible parent categories for special tickets.
• Channel Access Roles: additional roles that can view ticket channels.

Role setup by type

• Regular Regear Roles: role list shown in regular flow select menu.
• Special Regear Roles: role list shown in special flow select menu.
• Special required roles: optionally lock a specific special role behind a Discord role requirement.
• Role icons: used in select menu options.

System Status

Keep system active. If inactive, request creation flow returns configuration error and no ticket is created.

Activation Checklist

1. Fill channels: Embed Channel, Regear Log Channel, Staff Role (and Transcription Channel if needed).
2. Configure regular/special categories and role lists.
3. Save configuration.
4. Click Send Embed to publish the public request message.
5. Run a live test: create one regular request and close it as staff.

Request Flow (End User)

1. User clicks Request Regear or Special Regear on the public embed.
2. Bot replies ephemeral with a role select menu for chosen type.
3. User picks role from dropdown.
4. Bot validates system state and permission rules.
5. Bot creates private ticket channel in an eligible category.
6. Bot sends ticket embed with action buttons inside the new ticket channel.

Validation logic during creation

• Blocks when system is inactive or misconfigured.
• Blocks if user already has an open request of same type.
• In special flow, enforces required Discord role for selected special role when configured.
• Rejects creation if no category is available.

Channel creation behavior

• Ticket number is generated per guild and request type.
• Channel name includes ticket number, selected role, and player/user identifier.
• Channel permissions include requester, staff role, and optional allowed roles.
• Status starts as open in database.

Buttons and Interactions

Public embed buttons

• Request Regear (request_regear): starts regular flow.
• Special Regear (request_special_regear): starts special flow.

Role select interaction

• Custom id format: regear_role_select:<type>.
• After selection, ticket channel is created and request record is inserted.

Ticket action buttons

Cancel Request

• Button id: cancel_regear.
• Only requester can cancel.
• Opens modal for optional cancel reason.
• Updates status to cancelled, logs event, generates transcription, deletes ticket channel after short delay.

Regear Done

• Button id: regear_done.
• Only members with configured staff role can execute.
• Opens modal requiring regear location.
• Updates status to completed, logs event, DMs requester, generates transcription, deletes channel after delay.

Deny Regear

• Button id: deny_regear.
• Only members with configured staff role can execute.
• Opens modal requiring denial reason.
• Updates status to denied, logs event, DMs requester, generates transcription, deletes channel after delay.

Data Model

RegearConfig (configuration table)

• One row per Discord guild (guildId unique).
• Stores channel IDs, staff role, active flag, role mappings, icons, category arrays, and embed customization.
• Contains both regearLogChannelId and optional transcriptionChannelId.

RegearRequest (request lifecycle table)

• Stores request identity: guild, user, channel, category, type, role.
• Lifecycle fields: cancelled/completed/denied metadata and timestamps.
• Status enum: open, cancelled, completed, denied.
• Unique index on channelId to enforce one ticket record per channel.

Status lifecycle

• open -> cancelled: requester cancels.
• open -> completed: staff resolves and provides location.
• open -> denied: staff denies with reason.

Logs and Transcription

Logs

• Regear log channel: specialized regear events (cancel/complete/deny).
• General setup log channel: mirrored critical events to main bot log stream.
• New request creation is logged to general bot log channel.

Transcription behavior

• If transcription channel is configured, bot posts metadata and ticket conversation on close.
• Conversation includes message replay with attachment handling and separator marker.
• Triggered when ticket ends by cancellation, completion, or denial.

Troubleshooting

• "Regear system is not configured": activate and save configuration in Regear System page.
• "No categories configured": fill regular/special categories in dashboard.
• Requester cannot open special role: verify Special Required Role mapping for selected special role.
• Staff cannot complete/deny: check Staff Role and member role assignment in Discord.
• No transcription generated: configure Transcription Channel and verify bot write permissions.
• No logs received: verify Regear Log Channel and setup log channel IDs.