The Viscra Guide

A complete manual for setting up and mastering Viscra for your community.

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.

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)

Note: Viscra's role must be higher in the Discord role hierarchy than the roles it is trying to manage.

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}

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

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

Configuration (ViscraConfigs)


serverId = "YOUR_SERVER_ID",
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

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.

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.

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: https://discord.com/channels/1411468373803663523/1433403663740567615/1436849381612716032

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

Manage support tickets within your server. Below are the setup commands.

/settings set-ticket-category: Set the category in which new tickets will be opened within.
/settings set-transcript-chanel: Set the channel in which ticket logs will be sent.
/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 using the ticket-panel-id.

Ticket staff 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

9. 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.

Warning: The public API is intended for server-related data only. Do not use it to fetch personal user data without consent.

Base URL: https://api.viscra.uk/api

Auth: Header Authorization: YOUR_BOT_KEY (Get key via /getkey)

Endpoints

GET /server-info
Params: serverId
Returns: id, name, memberCount, iconUrl
GET /is-verified
Params: robloxId
Returns: isVerified, discordId
GET /user-xp
Params: serverId, robloxId
Returns: xp
GET /user-rank
Params: serverId, robloxId
Returns: groupId, rankName, rankId