Verse Architect Bot - User & Admin Manual
Version: 1.0 Last Updated: 2023-10-27 (Replace with current date)
Table of Contents
Introduction
For Server Owners/Bot Administrators
2.1. Initial Bot Setup & Permissions
2.2. Applying a Faction Theme (!theme apply)
2.3. Managing Themes (!theme list)
2.4. The Bot Administrator Role
For Theme Administrators
3.1. Managing XP (!addxp, !setxp)
3.2. Promotion Wizard (!promotewizard)
3.3. FAQ Management
3.4. Posting Links (!postlink)
3.5. Assigning Base Role (!assignbaserole)
For Officers
4.1. Creating Events (!createevent)
4.2. Moderation
4.3. Link Posting (!postlink)
For All Members
5.1. Getting Roles (Reaction Roles)
5.2. Checking XP/Rank
5.3. Giving Commendations (!commend or !rep)
5.4. Checking Commendations
5.5. Flavor Commands
5.6. Utility Commands
Bot Commands Quick Reference
Troubleshooting / FAQ for Bot Issues
-
Introduction
Welcome to the Verse Architect Bot! This bot is designed to help you create and manage an immersive, faction-themed Discord server for your Star Citizen organization or community. It can automatically set up roles, channels, and permissions based on various in-game factions, and provides tools for member engagement, progression, and server management.
Default Command Prefix: ! -
For Server Owners/Bot Administrators
These commands and procedures are typically for the person who initially sets up the bot on the server.
2.1. Initial Bot Setup & Permissions
Invite the Bot: Use the OAuth2 invite link provided by the bot developer.
Bot Role & Hierarchy:
When the bot joins, it will have a role (usually named after the bot itself, e.g., “VerseArchitectBot”).
Go to Server Settings > Roles.
Crucially, drag the bot’s role to be very high in the role list. It must be above all roles it will create or manage for the themes to apply correctly.
Grant this bot role the necessary permissions. For full functionality of !theme apply, “Administrator” is easiest during initial setup. Alternatively, use the granular list of permissions (refer to the bot’s documentation or the permissions list provided separately).
Create Bot Administrator Role:
Create a new role in your server named exactly Bot Administrator.
Assign this role to yourself and any other trusted individuals who should have full control over the bot’s theme management. This role is required to use the !theme commands.
2.2. Applying a Faction Theme (!theme apply)
This is the most powerful command and will restructure your server. Use with caution, preferably on a new server or one you are prepared to wipe and reconfigure.
Command: !theme apply <themename>
Permission: Requires the Bot Administrator role.
Action:
If <themename> is invalid, it will suggest using !theme list.
If a valid <themename> is given:
The bot will ask if you want to customize the name of the theme’s default “auto-join” role (e.g., “Civilian Pilot” for UEE). You can type a new name or skip.
It will then issue a WARNING that applying the theme will delete non-theme roles and channels (unless they are in the theme’s protectedElements list).
You must type the exact confirmation phrase (e.g., CONFIRM WIPE FOR Your Server Name) to proceed.
The bot will then execute the theme application process.
Example: !theme apply uee_controlled_space
2.3. Managing Themes (!theme list)
Command: !theme list
Permission: Requires the Bot Administrator role.
Action: Lists all available faction themes that can be applied using !theme apply <themename>.
2.4. The Bot Administrator Role
This role (default name: “Bot Administrator”) is for users who have the highest level of control over the bot’s core functions, primarily changing the server’s theme.
It is distinct from the theme-specific admin roles (like “UEE High Command”). It grants permission to use !theme apply and !theme list.
- For Theme Administrators
(e.g., “UEE High Command”, “Pirate Lord”, or users with the Bot Administrator role)
Once a theme is applied, the user with the role defined as adminRoleName in that theme OR a Bot Administrator can use these commands.
3.1. Managing XP (!addxp, !setxp)
!addxp @User <amount> [reason]: Gives a specified amount of XP to a user.
Example: !addxp @JohnStanton 100 For successful mission completion
!setxp @User <amount>: Sets a user’s total XP to a specific value. This will also recalculate their level.
Example: !setxp @JaneAvery 1500
3.2. Promotion Wizard (!promotewizard or !checkpromotion)
Command: !promotewizard @User
Action: Checks a user’s eligibility for promotion based on their current XP/Level and prerequisite roles within the active theme. It can also facilitate the promotion.
3.3. FAQ Management
!addfaq <keyword> <answer>: Adds a new entry to the FAQ databank.
Example: !addfaq jumpoint To find new jump points, use your ship’s scanner in unknown regions.
!editfaq <keyword> <new_answer>: Edits an existing FAQ entry.
!delfaq <keyword>: Deletes an FAQ entry.
!listfaqs: (Usable by everyone) Lists all available FAQ keywords.
3.4. Posting Links (!postlink)
Command: !postlink #<category_tag> <url> [description]
Action: Posts a formatted link to the theme’s designated “intel-feed” channel.
Valid Category Tags: #news, #patch, #ship, #community, #lore, #event, #sale
Example: !postlink #patch https://robertsspaceindustries.com/comm-link/SCANTU-ALPHA-3.23 Patch 3.23 is now live!
3.5. Assigning Base Role (!assignbaserole)
Command: !assignbaserole [“Role Name”]
Action: Mass assigns the specified role to all non-bot members who don’t already have it. If no role name is provided, it uses the autoRoleOnJoinName from the current theme.
- For Officers
(e.g., “Fleet Commander”, “Quartermaster”, as defined in OFFICER_ROLES_BY_THEME for the active theme)
4.1. Creating Events (!createevent)
Command: !createevent
Action: Starts an interactive process to create a new event, prompting for details like name, time, description, etc.
4.2. Moderation
(Permissions for these actions also depend on the officer role having the necessary Discord permissions).
!warn @User [reason]: Issues an official warning/infraction.
!infractions @User (or !warnings, !history): Shows warning history.
!clearinfraction <warning_id> (or !delwarn, !clearwarn): Clears a warning.
4.3. Link Posting (!postlink - if granted)
Officers may also be able to use !postlink if their role is configured with this permission within the bot (currently defaults to Theme Admins/Bot Admins).
-
For All Members
5.1. Getting Roles (Reaction Roles)
Navigate to the channel specified in the theme for role selection (e.g., #career_path_selection, #job_board_dirty_deeds).
React with emojis to gain or remove roles (career paths, faction affiliations, regional roles).
Some roles may have prerequisites.
5.2. Checking XP/Rank
Command: !checkxp [@User] (or !level, !rank, !servicelevel)
Action: Shows your (or a mentioned user’s) XP, level, and progress.
5.3. Giving Commendations (!commend or !rep)
Command: !commend @User [reason]
Action: Gives +1 reputation/commendation to another user (cooldown applies).
5.4. Checking Commendations
Command: !commendations [@User] (or !repcheck, !reputation)
Action: Shows commendation points for yourself or a mentioned user.
5.5. Flavor Commands
!verse_quote: Displays a random Star Citizen quote.
!ship_scan [@User]: Gives a “scan report”.
!comm_intercept: Shows a fictional intercepted communication.
!flight_review [@User]: Gives a humorous piloting skill review.
5.6. Utility Commands
!info: Basic bot info.
!status: Bot operational status.
!squadroninfo (or !serverinfo): Server statistics.
!faq <keyword>: Retrieves an FAQ entry.
!listfaqs: Lists all FAQ keywords.
!poll “Question” “OptionA” …: Creates a poll. -
Bot Commands Quick Reference
Bot Administrator Only (Bot Administrator role):
!theme apply <themename>
!theme list
Theme Administrator (Theme’s adminRoleName or Bot Administrator):
!addxp @User <amount> [reason]
!setxp @User <amount>
!promotewizard @User
!addfaq <keyword> <answer>
!editfaq <keyword> <new_answer>
!delfaq <keyword>
!postlink #<category> <url> [description]
!assignbaserole [“Role Name”]
Officers (Roles in OFFICER_ROLES_BY_THEME for active theme, or Theme/Bot Admins):
!createevent
!warn @User [reason]
!infractions @User
!clearinfraction <warning_id>
(!postlink if configured for officers)
All Members (Permissions may vary for some):
!checkxp [@User] / !servicelevel [@User]
!commend @User [reason]
!commendations [@User]
!verse_quote
!ship_scan [@User]
!comm_intercept
!flight_review [@User]
!info
!status
!squadroninfo
!faq <keyword>
!listfaqs
!poll “Question” “OptionA” …
!temprole @User “Role Name” <duration> [reason] (Requires Discord “Manage Roles” perm)
!prune <number> (Requires Discord “Manage Messages” perm)
!announce <message> / !embed <message> (Requires Discord “Manage Messages” perm) -
Troubleshooting / FAQ for Bot Issues
Bot is offline or not responding:
Contact the server/bot administrator. They can check server logs (pm2 logs <bot_process_name>).
Ensure the bot has an internet connection and the BOT_TOKEN is correct.
!theme apply fails or gets stuck:
Bot Permissions: The bot’s own role MUST have Administrator permissions (or a comprehensive set of granular permissions) AND be very high in the server’s role hierarchy.
Rate Limits: This command makes many changes. If it fails mid-way, the server might be partially configured. Contact a Bot Administrator.
Reaction roles not working:
The reaction role message might be outdated if the theme was recently re-applied.
The bot might lack Manage Roles or Add Reactions permissions in the specific channel.
Command says “Unauthorized”:
You may not have the required role for that command (e.g., Bot Administrator, the theme’s specific admin/officer role, or necessary Discord permissions like “Manage Messages”). Check with a server admin.
