The Viscra Guide

1. Base Setup

Getting Viscra into your server is the first step. Ensure you have the correct permissions set up to avoid issues later.

Adding the Bot

Invite Viscra using the official invite link. You need Manage Server permissions to add bots.

White-labelling (Custom Bots)

Viscra allows you to use your own custom bot identity (name, profile picture, banner) while still powered by our engine.

1. Create a new application at the Discord Developer Portal or use an existing one.
2. Go to the Bot tab and ensure Server Members Intent and Message Content Intent are both enabled.
3. Head to the Installation tab. Change the Install Link from "None" to "Discord Provided Link". Under Default Install Settings, add "Bot" and "applications.commands" to scopes, and set permissions to Administrator.
4. Copy your Application ID and Bot Token.
5. In the Viscra Dashboard, navigate to your server settings, go to the Pro page, and enter these credentials.

Please ensure you have enabled intents under the Bot tab on the application page.

1. Server Members Intent
2. Message Content Intent

Tip: If you want to hide the original Viscra commands and only show your custom bot's commands, go to Server Settings > Integrations > Viscra. Set the permissions for "Roles & Members" and "Channels" to false. This will hide them for non-admins.

Recommended Permissions

We recommend giving Viscra Administrator permissions for ease of use. If you prefer granular control, ensure the bot has:

• Manage Roles (to assign rank/verified roles)
• Manage Nicknames (to update names to Roblox usernames)
• Manage Channels (for tickets)
• View Channels, Send Messages, Embed Links (basic functionality)
• Moderate Members (for kicks/bans/timeouts)

2. Verification System

Viscra uses Roblox's official OAuth2 for secure verification. No verification games or code phrases are required.

Setting Up Roles

Use /settings to configure the basic roles:

• /settings set-verified-role: The role given to users who successfully verify.
• /settings set-unverified-role: The role given to new members (removed upon verification).

The Verification Panel

Run /verifypanel in your verification channel. This creates a permanent button that users can click to link their account.

3. Rank & Group Binds

Connect your Roblox group ranks to Discord roles. This can be done via commands or the Dashboard.

Quick Setup

Run /setup groupid:YOUR_GROUP_ID. Viscra will fetch your group roles and offer to automatically create corresponding Discord roles and binds for them.

Manual Binds

• Group Bind: Gives a role to anyone in the group.
  /groupbind add-role groupid:123 roles:@Member
• Rank Bind: Gives a role to a specific rank ID.
  /rankbind add-role groupid:123 rankid:255 roles:@Owner
• Rank Bind (ranged): Gives a role to a range of rank IDs.
  /rankbind add-role groupid:123 rankid:20-32 roles:@Officer

Naming Schemes

Optionally, You can enforce nickname formats per rank using the dashboard or /rankbind command. Use {roblox_username} as a placeholder.
Example: [E1] {roblox_username}

Sticky Roles

Sticky roles are roles that Viscra will not remove from a user, even if they no longer meet the requirements for it. This allows roles to be given via binds but not removed.

Roles within this list will not be removed by the bot when /update, /updateall, or the verification panel is interacted with.

• /stickyroles add role: - Add a role to the sticky role list.
• /stickyroles list - List all currently configured sticky roles.
• /stickyroles remove role: - Remove a role from the sticky role list.

4. In-Game Systems

Sync your game with Viscra to enable XP tracking, auto-promotions, and more. You will need the Viscra Handler script from our support server.

Installation

1. Get the ViscraHandler_New script and ViscraConfigs ModuleScript.
2. Place ViscraHandler_New in ServerScriptService.
3. Place ViscraConfigs in ServerStorage.
4. Enable HTTP Requests and Studio Access to API Services in Game Settings.

Configuration (ViscraConfigs)

serverId = "YOUR_SERVER_ID",
APIKey = "YOUR_GAME_API_KEY",
GroupId = 123456, -- Your Group ID
XPEarningTeams = {game.Teams.Red, game.Teams["Blue Team"]}, -- Teams that earn XP
XPSystemEnabled = true, 
statName = "XP", -- The leaderstat to track, name doesn't matter much for Viscra's side of things
            

API Key Configuration

GameLink Authorisation

For Viscra to rank users on Roblox, you must authorise GameLink. Run /settings set-gamelink-auth and follow the OAuth flow. This replaces the old cookie system.

GameLink is also required for the dashboard to view group icons and group rank names.

Extensions & Attributes

• ProgressionBar: Add a Boolean attribute named ProgressionBar (set to true) to ReplicatedStorage to show a UI bar to players.
• ProgressionBarTheme: Create a String attribute ProgressionBarTheme on ReplicatedStorage to customize the UI bar's appearance, below are the themes currently added:
• Default - The standard white-grey theme.
• SciFi - A black-white less rounded theme.
• SciFi2 - A black-white less rounded theme with a visible container for the progress to next rank text.
• Tactical - Black and white with an orange-yellow touch, positioned in the left lower corner of your screen.
• Custom - Your own custom theme, Copy the ViscraXPBar StarterGui and paste it under ReplicatedStorage (after modifying it to your liking) and it'll have your custom modifications! You must keep the default hierarchy & naming, but other than that you're free to modify colours, positions, sizes, effects, etc.
• GamepassGifting: Set a Boolean attribute GamepassGifting on ReplicatedStorage to true to enable gamepass gifting.
• 2xXP: Set a Boolean attribute 2xXP on a Player object to true to grant double XP.
• CanEarnXP: Set to false on a Player to pause XP earning (useful for AFK zones).
• Cmdr Commands: This comes with XPAdd & XPRemove with support for bulk updating in-game. To add this extension go to your Cmdr ModuleScript in ServerScriptService, find Initialize and open it, then add the below segment directly under local ReplicatedRoot, RemoteFunction, RemoteEvent:

  game:GetService("ReplicatedStorage"):WaitForChild("ViscraExtensions"):WaitForChild("Assets"):FindFirstChild("CmdrCommands"):Clone().Parent = script.Parent.BuiltInCommands

• EventSystem: Enables the Viscra handler to sync in-game players with the bot during events, as well as handling teleporting to the private server. This is a Boolean attribute that can be set on ReplicatedStorage, set to true to enable the system.

Gamepass gifting

1. You can gift players gamepasses directly through Viscra, this is setup via an API integration in your game. To set up this follow the setup below:
2. Run the command /gamepass configure universe_id: to setup your games universeId (can also be done via the settings command),
3. Using our new endpoint, /api/getGiftedGamepasses, you can setup whatever type of gamepass gift integration you want, such as vehicles, morphs, tools, etc.
   I have provided an example script - here as a guide to integrating it into your own systems.
   Someone with programming knowledge will need to modify this to fit your game, this is just an example. You'll also need to enable the extension which yu can find under the in-game systems section of this guide.
4. To gift a gamepass to a user, use the command /gamepass gift user: roblox_username/@Mention pass: [autofilled], you can gift multiple gamepasses by running this multiple times.
5. You can view a list of gifted gamepasses using the command /gamepass view user: roblox_username/@Mention.
6. You can revoke a gifted gamepass using the command /gamepass revoke user: roblox_username/@Mention pass: [autofilled].
7. Only those with Administrator permissions or a gamepassGifterRole can gift gamepasses.

You can modify the gamepass gifter roles with the following commands:

• /settings gamepass-gifter-role view to view existing gamepass gifter roles
• /settings gamepass-gifter-role add role: to add a new gamepass gifter role
• /settings gamepass-gifter-role remove role: to remove one

5. XP & Promotions

Once your game is connected, Viscra can track XP and promote users automatically.

Promotion Configuration

In your ViscraConfigs script, define the promotionReqs table:

promotionReqs = {
            [1] = { -- Starting rank in your group, EG: Cadet
                statReq = 0,     -- XP needed
                groupRoleId = 1 -- Rank ID to promote to
            },
            [2] = { -- Next rank, EG: Trooper
                statReq = 15,
                groupRoleId = 2
            }
            }

Whenever a server starts, these requirements are synced to Viscra.

Commands

• /xp: View your own or another user's XP and progress to the next rank.
• /topxp: View the server leaderboard, top 10 users with the most XP. For performance this value is cached for 5 minutes.
• /xpchange add: (Officer+) Add XP to a users existing XP amount.
• /xpchange remove: (Officer+) Remove XP from a users existing XP amount.
• /xpchange set: (Officer+) Set a user's XP to a specific amount.

You can modify the officer roles with the following commands:

• /settings officer-role view to view existing officer roles
• /settings officer-role add role: to add a new officer role
• /settings officer-role remove role: to remove one

6. LOA & EP/Quotas

The Quota/Event Point (EP) system is designed for activity tracking within divisions or units.

Setup

Run /ep setup to start the interactive configuration wizard. You can define:

• Units: Up to 4 units (Main, Sub1, Sub2, Sub3), each with a Discord Role and a Weekly Quota.
• Warnings: Define actions for failing quota (Warn, Demote, or Exile/Kick).

LOA

Members can request Leave of Absence (LOA) in a channel created by server admins which can then be managed however you wish. Users on LOA are not counted during te weekly EP check, the LOA commands are as follows:

• /loa add: Set a user as on LOA.
• /loa end: End a user's LOA early.
• /loa viewall: View everyone on LOA within your server.
• /loa set-role: Set the role assigned to users on LOA.

How it works

Viscra tracks EP earned via /ep add. Every week (Sunday 00:00 UTC), the bot checks if users met their unit's quota. If they fail, the configured warning action is applied automatically.

7. Medals & Warnings

Medals

Award custom medals to your members to recognise achievements.

• /medal view: View a user's medals.
• /medal list: List all medals created.
• /medal create: Create a new medal.
• /medal award: Give a medal to a user.
• /medal edit: Edit an existing medal.
• /whois: View a user's medals (and other info).

Medals can be displayed ingame via our integration onto DarthKarim's mouse rank system, alternatively if you are (or know a programmer) you can integrate it into your own in-game display.

You can get our integration for Karim's system from our server here.

Warnings

A robust warning system logged to your database.

• /warn view: View a user's warnings.
• /warn add: Warn a user. They will be DM'd the reason and a Warning ID.
• /warn remove: Remove a warning using its ID.

Warning permissions are managed by the server moderator roles, you can view/manage them with the following commands:

• /settings server-moderator-role view to view existing moderator roles
• /settings server-moderator-role add role: to add a new server moderator role
• /settings server-moderator-role remove role: to remove one

8. Tickets

Viscra provides an expansive ticket system with support for categories, custom naming schemes for channels made, and dedicated staff roles.

Core Commands

• /tickets create: Create a new support ticket panel.
• /tickets delete: Delete a support ticket panel using the ticket-panel-id.
• /tickets manage: Manage an existing ticket panel, including customising the initial embed text.
• /add [user]: Add a user to an active ticket.
• /close [reason]: Close the current ticket with an optional reason.

Ticket Categories

Categories allow you to route tickets to specific departments with their own settings.

• /tickets category add: Create a new ticket category.
• /tickets category edit: Modify an existing category's settings.
• /tickets category list: View all configured categories.
• /tickets category remove: Delete a ticket category.

Naming Schemes

Customise how ticket channels are named globally or per category.

• /tickets settings naming scheme: Configure the channel naming format.

Supported formats include:

• ticket-[username] (Default)
• support-[number]
• appeals-[username]

Settings & Staff

Ticket staff permissions are primarily managed by the server moderator roles.

• /settings server-moderator-role view/add/remove: Manage which roles can access and manage tickets.
• /settings set-ticket-category: Set the default Discord category for tickets without an assigned department.
• /settings set-transcript-channel: Set the channel for ticket logs. Note: Transcripts now exclude bot messages for better readability.

Embeds & Actions

When a user opens a ticket, they receive a message with a customisable embed. You can modify this text via the /tickets manage command.

The Close Ticket button on the embed will now prompt staff for a reason via a modal before the ticket is finalised.

9. Server Utilities

Powerful server management tools to streamline your community operations.

Applications System

Create custom application forms for your members to complete. Upon acceptance, the bot can automatically add them to a group and/or set their rank.

Commands

• /applications manage: View and manage all your server's applications.
• /applications create: Create a new application form with custom questions.
• /applications panel [id]: Send an application panel to the current channel for members to apply.

Features

• Up to 7 applications active at a time (14 for pro servers)
• Up to 15 questions per application (30 for pro servers)
• Accept, decline, make interview ticket, and mark submissions for review from the log channel
• Automatic DMs sent to users when their application is accepted or declined
• Ability to disable or delete applications via the manage option
• Automatic group acceptance and rank assignment upon approval

Group Logs

Track Roblox group changes such as promotions, demotions, and leaves in semi-real-time, logged directly to your Discord channels. This is limited to 1 primary group and 6 sub groups for free servers, and 1 primary group and 13 sub groups for pro servers. You'll need the token of an account with view audit log permissions to view group logs and send them to your channels.

Commands

• /grouplogs add: Add a Roblox group to be tracked. You can specify the logging type (e.g., Primary: HICOM only, Sub: All ranks + ping for HICOM changes) and the channel for logs.
• /grouplogs view: View all currently tracked groups in your server.
• /grouplogs sethicomrole: Set a specific Discord role to be pinged when a HICOM-level change occurs.
• /grouplogs settoken: Set the Roblox cookie/token to view the group logs for your server. (account needs view audit log permissions)
• /grouplogs delete: Stop tracking a specific Roblox group.
• /grouplogs antiabuse: Configure anti-abuse settings for a group to prevent nuking.
• /grouplogs rollback: (PRO) View and restore group snapshots to undo mass changes.

Features

• Semi-Real-time Tracking: Automatically detects rank changes and group leaves. Runs a scan every 60 seconds.
• HICOM Filtering: Option to only track high-ranking members (HICOM) to reduce log clutter.
• Custom Pings: Ping specific roles for certain rank changes.
• Detailed Logs: Embeds include the username, group name, old rank, and new rank.

Anti-Abuse & Rollbacks

Command Groups

Disable specific groups of commands to customize which features are available in your server.

• /commandgroups list: View all available command groups and their current status.

Available command groups include:

• Verification: Disables verify command, update command, and rank/group bind commands
• Economy: Disables gamepass gifting and the global economy system in your server

Server Backups

Create complete backups of your server configuration and restore them when needed.

Commands

• /backupserver: Create a backup of your server's current configuration.
• /backuprestore: Restore your server from a previous backup.

What Gets Backed Up

• All roles (including colors, permissions, and hoisted status)
• All channels and categories
• Channel permissions and settings
• Role hierarchy and positions

Anti-Abuse Measures

• Only the server owner can run backup or restore commands
• The bot requires Administrator permissions and the highest role in the server
• Commands can only be run once every 30 minutes to prevent spamming
• Restoration deletes all current roles, channels, and categories before applying the backup

10. Public API

Developers can use Viscra's public API to integrate server data into external tools or websites.

Requests to the public API are limited to 100 per minute per instance.

General Information

{ "id": "...", "name": "...", "memberCount": 0, "iconUrl": "..." }

{ "isVerified": true/false, "discordId": "..." }

{ "groupId": 0, "rankName": "...", "rankId": 0 }

XP Management

All XP routes return { "success": true, "newXp": 150 } or an error { "success": false, "error": "..." }.

{ "xp": 100 }

Group Management

Note: If groupId is not provided, the bot defaults to the server's configured Main Group.

{ "success": true, "data": [ { "id": "...", "user": { "userId": 123, "displayName": "..." } } ] }

{ "success": true, "newRole": { "name": "Captain", "rank": 50 } }