VoxelGuest

VoxelGuest5.png
An official Bukkit plugin from the VoxelBox suite
Lead Programmer & Designer: Monofraps
TheCryoknight
Editors: Deamon5550, MikeMatrix, thedeadlybutter
Documentation: Felryder, Monofraps
BukkitDev Link: N/A
Tested Compatible With: 1.5.1-R1.0
Source: Source
DevBuilds: CI Server
Issue Tracker: BugTracker
Soft-dependencies: Vault
Download: Latest Stable Release (5.0.1)

VoxelGuest is a powerful user management and server administration suite that functions as a conglomerate of modules, each with a distinct purpose. The concept of a greylist was first seen in early versions of VoxelGuest and has since become the core of user management on The Voxel Box.

Contents

Installation

  1. Download VoxelGuest.jar and place it into your /plugins/ folder.
  2. Restart/reload your server twice. Module configuration files will not be generated upon first restart/reload.

Generated Files

  • persistence.db - Stores all module data. More information is detailed below.
  • AsshatModule.properties - Contains settings that influence the functionality of the asshat module. More information is detailed below.
  • GeneralModule.properties - Contains settings that influence the functionality of the general module. More information is detailed below.
  • GreylistModule.properties - Contains settings that influence the functionality of the greylist module. More information is detailed below.

Persistence

  • The persistence database (persistence.db) stores:
    • Region Data
      • Region name, world name, relevant coordinates, building enable/disable flag, other region flags
    • Greylist Data
      • Greylistee name
    • Mute Data
      • Player name, mute reason
    • Ban Data
      • Player name, ban reason
    • Helper Data
      • Player name
    • AFK Data
      • Random AFK messages

Migration

Migration from VoxelGuest 4.x

If you are using VoxelGuest 4.x you will not be able to import most of your data yet. However, we are working on more import functionality.

  1. Delete the old VoxelGuest jar file from your plugins directory.
  2. Download VoxelGuest.jar and place it into your /plugins/ folder.
  3. Restart/reload your server twice. Module configuration files will not be generated upon first restart/reload.
  4. Call the /vgimport (VoxelGuest Administration System) command to import your old data.

Migration from VoxelGuest 5.0 development builds

If you are using a development build of VoxelGuest 5.0 you need to manually update your database file or delete it (all persistent data like bans, mutes, regions will be lost) and let the plugin generate a new one. You also need to update some configuration file names. Please note, upgrading from a development build to a release build is not officially supported. The steps below might be outdated. Furthermore, these steps are not meant to as a step-by-step or click-this-button-and-then-that-one tutorials. Especially the manual database upgrading part requires a bit database/SQL knowledge.

  1. Shut down(!!!) the server.
  2. Back up your files.
  3. Delete the old VoxelGuest jar file from your plugins directory.
  4. Download VoxelGuest.jar and place it into your /plugins/ folder.
  5. Rename the following files
    1. asshat.properties to AsshatModule.properties
    2. general.properties to GeneralModule.properties
    3. greylistmodule.properties to GreylistModule.properties
  6. Make sure the strings in your config files are enclosed with " characters (check default config files below)
  7. Manually update your database file (only required if really want to keep your persistent data)
    1. Get a program to read, modify and write SQlite databases.
    2. Open persistence.db and make sure the schema matches the one found in the database documentation section below.
  8. Start your server.

Database Schema

As mentioned above, the persistence.db file stores all persistent data. This includes things like bans, greylist entries and region data. The current schema of our SQlite database looks like this:

  • bans
    • id : INTEGER (PRIMARY KEY)
    • playerName : VARCHAR
    • banReason : VARCHAR
  • helpers
    • id : INTEGER (PRIMARY KEY)
    • name : VARCHAR
    • reviews : INTEGER
    • lastReview : BIGINT
  • moduleMetaData
    • moduleName : VARCHAR (PRIMARY KEY)
    • enabled : BOOLEAN
  • mutes
    • id : INTEGER (PRIMARY KEY)
    • playerName : VARCHAR
    • muteReason : VARCHAR
    • selfUngag : BOOLEAN
  • regions
    • id : INTEGER (PRIMARY KEY)
    • regionName : VARCHAR
    • worldName : VARCHAR
    • globalRegion : BOOLEAN
    • pointOneX : INTEGER
    • pointOneY : INTEGER
    • pointOneZ : INTEGER
    • pointTwoX : INTEGER
    • pointTwoY : INTEGER
    • pointTwoZ : INTEGER
    • buildingRestricted : BOOLEAN
    • mobSpawnAllowed : BOOLEAN
    • fireSpreadAllowed : BOOLEAN
    • leafDecayAllowed : BOOLEAN
    • blockGrowthAllowed : BOOLEAN
    • blockSpreadAllowed : BOOLEAN
    • blockDropAllowed : BOOLEAN
    • creeperExplosionAllowed : BOOLEAN
    • tntBreakingPaintingsAllowed : BOOLEAN
    • lavaFlowAllowed : BOOLEAN
    • waterFlowAllowed : BOOLEAN
    • dragonEggMovementAllowed : BOOLEAN
    • snowMeltingAllowed : BOOLEAN
    • iceMeltingAllowed : BOOLEAN
    • snowFormationAllowed : BOOLEAN
    • iceFormationAllowed : BOOLEAN
    • physicsAllowed : BOOLEAN
    • enchantingAllowed : BOOLEAN
    • creatureSpawnAllowed : BOOLEAN
    • bannedBlocks : BLOB
    • bannedItems : BLOB
    • pvpDamageAllowed : BOOLEAN
    • lavaDamageAllowed : BOOLEAN
    • cactusDamageAllowed : BOOLEAN
    • tntDamageAllowed : BOOLEAN
    • drowningDamageAllowed : BOOLEAN
    • explosiveDamageAllowed : BOOLEAN
    • fallDamageAllowed : BOOLEAN
    • fireDamageAllowed : BOOLEAN
    • poisonDamageAllowed : BOOLEAN
    • magicDamageAllowed : BOOLEAN
    • projectileDamageAllowed : BOOLEAN
    • hungerDamageAllowed : BOOLEAN
    • voidDamageAllowed : BOOLEAN
    • fireTickDamageAllowed : BOOLEAN
    • lightningDamageAllowed : BOOLEAN
    • suffocationDamageAllowed : BOOLEAN
    • foodChangeAllowed : BOOLEAN
    • soilDehydrationAllowed : BOOLEAN


The Asshat Module

The Asshat Module allows server staff to manage and restrict the extent to which a player may interact with the server. Banning, kicking, muting, freezing, and recalling ban data are all possible through this module.

Commands & Permissions

  • /ban
    • aliases: /vban
    • permission: voxelguest.asshat.ban
    • arguments: playername, reason, -si, -f
      • Bans the player specified in the playername argument from the server for the reason specified in the reason argument. Banned users may not reconnect to the server. If the specified player is online, player detection is enabled and the entire name need not be typed. Append the -si argument to prevent the ban notification and ban reason from being broadcast. Append the -f argument to ban an offline player. Names of offline players must be spelt completely with all numbers, letters, and symbols, but capitalization is not important.
  • /unban
    • aliases: /vunban
    • permission: voxelguest.asshat.unban
    • arguments: playername, -si
      • Unbans the player specified in the playername argument from the server. Append the -si argument to prevent the unban notification from being broadcast. Names of offline players must be spelt completely with all numbers, letters, and symbols, but capitalization is not important.
  • /banreason
    • aliases: /vbanreason
    • permission: voxelguest.asshat.banreason
    • arguments: playername
      • Returns the reason for which the player specified in the playername argument has been banned. Names of offline players must be spelt completely with all numbers, letters, and symbols, but capitalization is not important.
  • /kick
    • aliases: /vkick
    • permission: voxelguest.asshat.kick
    • arguments: playername, reason, -si
      • Kicks the player specified in the playername argument from the server. Append the -si argument to prevent the kick notification and kick reason from being broadcast.
  • /mute
    • aliases: /vmute, /gag, /vgag
    • permission: voxelguest.asshat.mute
    • arguments: playername, reason, -si
      • Denies the player specified in the playername argument the ability to speak in chat. Append the -si argument to prevent the mute notification and mute reason reason from being broadcast. Note: This is not compatible with iSay.
  • /unmute
    • aliases: /vunmute
    • permission: voxelguest.asshat.unmute
    • arguments: playername, -si
      • Re-allows the player specified in the playername argument the ability to speak in chat. Append the -si argument to prevent the unmute notification from being broadcast.
  • /soapbox
    • aliases: /vsoapbox
    • permission: voxelguest.asshat.soapbox
    • arguments: N/A
      • Denies all players the ability to speak in chat. Resend the command to re-allow all players the ability to speak in chat. Note: This is not compatible with iSay.
  • /freeze
    • aliases: /vfreeze
    • permission: voxelguest.asshat.freeze
    • arguments: N/A
      • Denies all players the ability to move. Resend the command to re-allow all players the ability to move.
Additional Permissions
  • voxelguest.asshat.bypass.silence - Prevents a player from being muted by soapbox.
  • voxelguest.asshat.bypass.freeze - Prevents a player from being movement impaired by freeze.

Configuration

Default Configuration
#Tue Jan 1 00:00:00 PST 2013
ban-message="§8Player §c%playername%§8 has been banned by §c%admin%§8 for\: §9%reason%"
gag-message="§8Player §c%playername%§8 has been gagged by §c%admin%§8 for\: §9%reason%"
asshat-reason="Asshat"
kick-message="§8Player §c%playername%§8 has been kicked by §c%admin%§8 for\: §9%reason%"
ungag-message="§8Player §c%playername%§8 has been ungagged by §c%admin%"
unban-message="§8Player §c%playername%§8 has been unbanned by §c%admin%"
Variables
  • %playername% - Returns the name of player specified in the argument playername.
  • %admin% - Returns the name of the player executing the command.
  • %reason% - Returns the reason for the action specified in the argument reason.
Explanation
  • ban-message - Defines the format of the message displayed to all users when a player is banned.
  • gag-message - Defines the format of the message displayed to all users when a player is gagged.
  • asshat-reason - Defines the default value for the %reason% variable.
  • kick-message - Defines the format of the message displayed to all users when a player is kicked.
  • ungag-message - Defines the format of the message displayed to all users when a player is ungagged.
  • unban-message - Defines the format of the message displayed to all users when a player is unbanned.

The General Module

The General Module contains useful commands for both staff and users of all usergroups. Users may view an organized list online players, track server TPS, and alert other users that they are going AFK. Staff may teleport to users, change usergroups, vanish, fakequit, and view system data.

Commands & Permissions

  • /who
    • aliases: /vwho, /list
    • permission: voxelguest.general.who
    • arguments: N/A
      • Lists all online players, organized by usergroup. Players flagged as AFK display a light gray name in the player list.
  • /vanish
    • aliases: /vvanish, /van
    • permission: voxelguest.general.vanish
    • arguments: N/A
      • Disallows all players without permission to vanish from seeing your character model or nameplate.
  • /fakequit
    • aliases: /fq, /vfq
    • permission: voxelguest.general.fakequit
    • arguments: N/A
      • Disallows all players without permission to vanish from seeing your character model or nameplate. Additionally disallows all players without permission to fakequit from seeing your name in the playerlist. A fake disconnect message is displayed on behalf of the player fakequitting.
  • /ep
    • aliases: /vep
    • permission: voxelguest.general.ep
    • arguments: world
      • Removes all entities except paintings and item frames in the specified world. The world argument can be replaced with an asterisk (*) to target all worlds.
  • /sys
    • aliases: /system, /vsys
    • permission: voxelguest.general.sys
    • arguments: gc, mem, lag
      • Returns information regarding CPU performance and memory usage amongst other data. Append the argument mem to return much more detailed memory usage data. Append the argument lag to return only server TPS (ticks per second). Append the argument gc to free RAM by triggering the native java garbage collector.
  • /vpg
    • aliases: /vpromote
    • permission: voxelguest.general.vpg
    • arguments: playername, usergroup
      • Assign the usergroup specified in the usergroup argument to the player specified in the playername argument.
  • /vtp
    • aliases: /vteleport
    • permission: voxelguest.general.vtp
    • arguments: playername, me, x# y# z#
      • Teleport to the player specified in the playername argument. Append the argument me to teleport the player specified in the playername argument to you. Append the x# y# z# argument to adjust the destination coordinates of the teleported player relative to the target player.
  • /afk
    • aliases: /vafk
    • permission: voxelguest.general.afk
    • arguments: reason
      • Flags your account as AFK for the reason specified in the reason argument and displays a message indicating the action to all players on the server. If the reason argument is excluded, an AFK message is selected at random from a list of random AFK messages.
  • /addafkmessage
    • aliases: /addafkmsg, /vaddafkmsg
    • permission: voxelguest.general.createafkmsg
    • arguments: reason
      • Adds an AFK message that may be selected at random when a player goes AFK, but excludes a reason for going AFK.
  • /watchtps
    • aliases: /vwatchtps
    • permission: voxelguest.general.watchtps
    • arguments: N/A
      • Rather than displaying your current experience level, your experience bar will display the server's TPS and update in real time. Resend the command to return your experience bar to displaying your current experience level.
  • /vgpg
    • aliases: (none)
    • permission: voxelgust.general.playergroup
    • arguments: colors, [group-name] [color]
      • Allows to create a VoxelGuest player group that maps permission system group names (the [group-name] argument) to /who group colors (the [color] argument). Passing colors as the only argument will show all available colors.

Configuration

Default Configuration
#Tue Jan 1 00:00:00 PST 2013
fakequit-prefix="§8[§cFQ§8]"
leave-format="§8(§6$no§8) §3$n§7 left"
permgen-shutdown-threshold=80
permgen-warning-threshold=65
force-watch-tps=true
join-format="§8(§6$no§8) §3$n§7 joined"
random-afk-messages=true
kick-format="§8(§6$no§8) §3$n§4 was kicked out"
Variables
  • $no - Returns the number of currently online players.
  • $n - Returns the name of the triggering player.
Explanation
  • fakequit-prefix - Defines the prefix applied to players in fakequit mode in the player list for people who have the fakequit permission.
  • leave-format - Defines the format of the message displayed to all users when a player disconnects from the server.
  • member-color - Defines the color of the member usergroup representation in the player list.
  • permgen-shutdown-threshold -
  • permgen-warning-threshold -
  • force-watch-tps - States whether the watchtps feature is enabled for players by default.
  • join-format - Defines the format of the message displayed to all users when a player connects to the server.
  • random-afk-messages - States whether random AFK messages are displayed when no reason argument is provided when sending the AFK command.
  • kick-format - Defines the format of the message displayed to all users when a player is forcibly removed from the server.

The Greylist Module

The Greylist Module allows a server's administration to filter direct access to the server through greylisting and whitelisting, and control demographics through a very simple and effective system.

Commands & Permissions

  • /greylist
    • aliases: /gl
    • permission: voxelguest.greylist.greylist
    • arguments: playername
      • Greylists the player specified in the playername argument. Greylisted users may access the server at any time. This command automatically promotes the player specified in the playername argument to the usergroup defined as the gl-group-name in the greylist module configuration.
  • /ungreylist
    • aliases: /ugl
    • permission: voxelguest.greylist.ungreylist
    • arguments: playername
      • Ungreylists the player specified in the playername argument.
  • /whitelist
    • aliases: /wl
    • permission: voxelguest.greylist.whitelist
    • arguments: playername
      • Whitelists the player specified in the playername argument. This command automatically promotes the player specified in the playername argument to the usergroup defined as the wl-group-name in the greylist module configuration.
Additional Permissions
  • voxelguest.greylist.override - Allows the usergroups granted this permission to override greylist restrictions.

Configuration

Default Configuration
#Tue Jan 1 00:00:00 PST 2013
exploration-mode=false
wl-group-name="Member"
stream-port=8080
gl-group-name="Guest"
not-greylisted-kick-message="You are not greylisted."
set-group-on-graylist=true
stream-enable=false
stream-password="changeme"
Explanation
  • exploration-mode - States whether non-greylisted users will be allowed to join the server.
  • wl-group-name - Sets the Member usergroup's name (used in whitelisting).
  • stream-port - Sets the port to listen on for the greylist stream. The Voxel Box only.
  • gl-group-name - Sets the Guest usergroup's name (used in greylisting).
  • not-greylisted-kick-message - Defines the format of the disconnect message displayed to users who are not greylisted and cannot join the server.
  • set-group-on-graylist - States whether a user's group will be changed upon greylist/whitelist.
  • stream-enable - States whether to listen on the greylist stream port. The Voxel Box only.
  • stream-password - Sets the greylist stream password. The Voxel Box only.

The Helper Module

The Helper Module serves as a systematic method of communication between guests and helpers. Logs are maintained to keep statistical data regarding the frequency of a player's interaction with the module and helper notes regarding feedback for players that use the module's functionality.

Commands & Permissions

  • /wlreview
    • aliases: /vwlreview
    • permission: voxelguest.helper.wloveride
    • arguments: N/A
      • Submits a ticket to helpers indicating that the triggering player would like to be reviewed for whitelisting. Note: The permission listed disallows the triggering player from submitting a ticket.
  • /helper
    • aliases: /vhelper
    • permission: voxelguest.helper.helper
    • arguments: -add, -remove, playername
      • Adds or removes the player specified in the playername argument from the list of helpers, dependent upon whether -add or -remove was appended before the playername.
  • /helperreview
    • aliases: /hreview
    • permission: voxelguest.helper.review
    • arguments: -h, -c, comment
      • Allows a helper to examine the helper review history of a player or comment on one instance of a player's review history, dependent upon whether -h or -c and a comment were appended.
Additional Permissions
  • voxelguest.helper.adminhelper

The Region Module

The Region Module is an extremely powerful module that allows various properties that modify environmental, block, and player interaction behavior to be applied to either entire worlds or defined areas.

Commands & Permissions

  • /vgregion
    • aliases: /vregion
    • permission: voxelguest.regions.modifyregion
    • arguments: create, help, edit, remove, regions
      • Appending the help argument returns the region creation command syntax. There are no additional arguments after appending the help argument.
      • Appending the regions argument returns the current list of regions. There are no additional arguments after appending the region argument.
      • Appending the create argument will begin the region creation process--additional arguments are necessary. The following arguments succeed the create argument.
        • ARGUMENT 1: name
          • Sets the name of the region.
        • ARGUMENT 2 (option 1): global
          • Sets the region to encompass the entire world. All regions are created in the world that the triggering player is standing in.
          • As of official VoxelGuest 5.0 release the global region will be created automatically. The region will be named global_[worldname] (e.g. global_Facet for a world called Facet)
        • ARGUMENTS 2, 3, 4, 5 (option 2): x1 z1 x2 z2
          • Sets the X and Z values for two coordinates, between which the region will encompass.
        • FINAL ARGUMENTS: -flags
          • Sets region flags that dictate block properties and block interaction within the region. More information below.
      • Appending the edit argument will begin the region editing process--additional arguments are necessary.
      • Appending the remove argument will begin the region removal process--append a region name after the remove argument to permanently delete it.

Region Flags

By default, all flags are enabled, thus the behaviors they inhibit are disabled. You must include the flags you wish to disable to re-allow the functionality they inhibit.

Miscellaneous
  • -fs - fire spread
  • -ld - leaf decay
  • -bg - block growth
  • -bs - block spread
  • -bd - block drop
  • -ce - creeper explosion
  • -tbp - tnt breaking paintings
  • -lf - lava flow
  • -wf - water flow
  • -dem - dragon egg movement
  • -sm - snow melting
  • -im - ice melting
  • -sf - formation of snow
  • -if - formation of ice
  • -en - enchantment
  • -phy - block physics
  • -bb - banned blocks
  • -bi - banned items
Player-related
  • -pvp - player vs. player damage
  • -lad - lava damage
  • -cd - cactus damage
  • -tntd - tnt damage
  • -dd - drowning damage
  • -exd - explosives player damage
  • -fad - fall damage
  • -fid - fire damage
  • -poid - poison damage
  • -mad - magic damage
  • -prod - projectile damage
  • -hund - hunger damage
  • -void - void damage
  • -ftd - fire tick damage
  • -lid - lightning damage
  • -sud - suffocation damage
  • -flc - food change

VoxelGuest Administration System

The Administration System encompasses several commands to manage VoxelGuest.

Commands & Permissions

  • /vmodules
    • aliases: /vgmodules
    • permission: voxelguest.manage.modules
    • arguments: -list|-l, -e [module name], -d [module name]
      • Allows you to enable and disable modules on the fly.
        • ARGUMENT 1: -list (alias: -l)
          • Lists all available modules.
        • ARGUMENT 2: -e [module name]
          • Allows to enable a module.
        • ARGUMENT 3: -d [module name]
          • Allows to disable an enabled module.
  • /vgimport
    • aliases: /voxelguestimport, /guestimport, import
    • permission: voxelguest.manage.import
    • arguments: -bans, -greylist, -afkmessages
      • Allows to import old data from VoxelGuest 4.x and 3.x
        • ARGUMENT 1: -bans
          • Imports banned players from VG 3.x and 4.x. The old file(s) have to be in the VoxelGuest folder in the plugins directory.
        • ARGUMENT 2: -greylist
          • Imports the greylist from VG 4.x. The old file(s) have to be in the VoxelGuest folder in the plugins directory.
        • ARGUMENT 3: -afkmessages
          • Imports the random AFK messages from VG 4.x. The old file(s) have to be in the VoxelGuest folder in the plugins directory.
Available Module Names
  • AsshatModule
  • GeneralModule
  • GreylistModule
  • HelperModule
  • RegionModule