Vexal Quicksand

A lightweight Spigot/Paper plugin that turns selected blocks (e.g., sand, soul sand) into smooth, configurable quicksand. Players gradually sink, struggle to escape by jumping, and may take suffocation damage if submerged.

Requirements

  • Server: Spigot or Paper 1.17+ (api-version 1.17)

  • Java: 16+

  • Optional: WorldGuard 7.x for region flag control

    • A custom WorldGuard StateFlag named quicksand is registered when WorldGuard is present.

Paper is recommended for best jump escape behavior (uses PlayerJumpEvent if available). On Spigot, upward movement still grants escape windows.

Installation

  1. Download the plugin JAR and place it in your plugins folder.

  2. (Optional) Install WorldGuard if you want region control via a flag.

  3. Start or restart your server. The plugin will generate config.yml and messages.yml in plugins/VexalQuickSand/.

  4. (Optional) Configure settings and then run /vqs reload or restart.

Features

  • Choose which blocks act as quicksand (default: SAND, RED_SAND, SOUL_SAND)

  • Enable per-world via an allow-list (enabled-worlds)

  • Smooth sinking with configurable speed and tick interval

  • Jump-to-escape with tweakable jump power (Paper) and skip-intervals

  • Optional sink depth limit (stop sinking after X blocks)

  • Optional suffocation damage and blindness while submerged

  • Optional particles around sinking players

  • Optional slowness and slow falling while sinking

  • Configurable action bar and chat messages (color tags & hex supported)

  • Per-player trace logging for troubleshooting (/vqs debug)

  • Optional WorldGuard flag to allow/deny quicksand per region, with per-world defaults

Commands

  • /vqs — Shows help

  • /vqs reload — Reloads configuration and messages (admin)

  • /vqs debug — Toggle trace for yourself (shows internal logic in console)

  • /vqs debug <player> [on|off|toggle] — Admin: manage trace for a target player

Examples:

  • /vqs debug — Toggle your own trace

  • /vqs debug on — Turn on your trace

  • /vqs debug Notch off — Turn off trace for Notch (admin)

Permissions

  • vexalquicksand.admin — Access to admin commands (reload, debug others). Default: OP

  • vexalquicksand.bypass — Player is immune to quicksand. Default: OP

Configuration Overview (config.yml)

Key sections and options:

  • debug (boolean): Enable extra console logging from the plugin.

  • quicksand-blocks (list): Material names that trigger quicksand logic.

  • enabled-worlds (list): Worlds where the effect is active. Empty list = all worlds.

Messages

  • messages.sinking.send_to_chat / send_to_action_bar: Where to show sinking notice

  • messages.sinking.action_bar_interval: Seconds between action bar messages

  • messages.escaped.send_to_chat / send_to_action_bar: Where to show escape notice

Mechanics

  • mechanics.sink-task-interval (ticks): How often the sink task runs. Lower = smoother, higher CPU. 20 ticks = 1 second.

  • mechanics.sink-speed: Downward speed (blocks per second). Effective motion per tick is derived from this and the interval.

  • mechanics.jump-escape-power: Vertical velocity applied on jump (Paper only) to help escape.

  • mechanics.jump-escape-skip-intervals: How many sink intervals to pause teleports after a jump/upward movement (escape window).

  • mechanics.escape-grace-millis: After escape, prevent immediate retrigger for this duration.

  • mechanics.apply-slow-falling / apply-slowness and slowness-level: Status effects while sinking.

Activation conditions

  • mechanics.minimum_cluster.enabled: Require a minimum number of quicksand blocks nearby.

  • mechanics.minimum_cluster.required_amount: Count of qualifying blocks in the search area.

  • mechanics.minimum_cluster.search_radius: 1 = 3x3x3, 2 = 5x5x5. Keep small to avoid lag.

  • mechanics.disable_in_liquid: If true, quicksand won’t trigger when player is in water/lava.

  • mechanics.sink_limit.enabled / depth: Cap how deep a player can sink before movement stops.

Suffocation

  • mechanics.suffocation.enabled: Deal damage while player’s head is inside quicksand.

  • mechanics.suffocation.damage-amount: Each damage application (1.0 = half heart).

  • mechanics.suffocation.damage-interval (ticks): Time between damage instances.

  • mechanics.suffocation.apply-blindness / blindness-level: Add blindness while submerged.

Particles

  • mechanics.particles.enabled: Toggle particles.

  • mechanics.particles.particle-type: e.g. FALLING_DUST. If the type needs block data, the plugin uses the ground block under the player.

  • mechanics.particles.count / radius: Visual density and spread.

WorldGuard Integration

  • worldguard.enable-flag (boolean): If true and WorldGuard is installed, the custom flag quicksand controls behavior in regions.

  • worldguard.worlds.<world> (boolean): Per-world default when a region doesn’t set the flag (used only if enable-flag is true and the region returns null for the flag).

WorldGuard: How To Use

  • The plugin registers a quicksand StateFlag.

  • To allow quicksand in a region: /rg flag <region> quicksand allow

  • To deny quicksand in a region: /rg flag <region> quicksand deny

  • If the flag isn’t set for a region, the plugin uses config.yml under worldguard.worlds.<world> to decide the default (true/false) for that world.

  • Set worldguard.enable-flag: true to enforce the flag; otherwise the plugin ignores the WG flag and just uses its own world/block rules.

Messages (messages.yml)

  • Supports <red>, <gold>, etc., hex colors like <#FFAA00>, and legacy & codes.

  • Configure prefix, sinking and escaped messages for chat and action bar, plus command messages.

Performance & Tuning Tips

  • Start with sink-task-interval: 4 and sink-speed: 0.7 (defaults in this repo) for smooth movement. Lower intervals are smoother but cost more CPU.

  • Keep minimum_cluster.search_radius small (1–2). Larger values scan more blocks and may cause lag.

  • Reduce particles.count or disable particles on busy servers.

  • Limit enabled-worlds to only where needed.

  • Avoid granting vexalquicksand.bypass widely if you want gameplay impact.

  • Use /vqs debug sparingly; tracing is verbose and intended for diagnostics.

Troubleshooting

  • “Nothing happens when standing on sand”

    • Check enabled-worlds (empty list means all worlds; otherwise your world must be listed)

    • Ensure the block type is in quicksand-blocks

    • If using WorldGuard with worldguard.enable-flag: true, verify the region flag: /rg info and set quicksand allow as needed, or configure per-world defaults.

    • Make sure the player doesn’t have vexalquicksand.bypass

    • If standing in water/lava and disable_in_liquid is true, quicksand won’t trigger

    • Cluster requirement: adjust minimum_cluster if a single block isn’t sufficient

  • “Players can’t escape”

    • Increase jump-escape-power (Paper only) and/or jump-escape-skip-intervals

    • Consider lowering slowness-level or increasing sink-task-interval

  • “Too much damage”

    • Tweak suffocation.damage-amount and damage-interval; or disable suffocation

Compatibility Notes

  • Spigot and Paper 1.17+. Built against Java 16 and Paper API 1.17.1.

  • Paper servers get improved jump handling via PlayerJumpEvent.

  • WorldGuard 7.x is supported for region flags.

Admin Reference

  • Reload: /vqs reload (requires vexalquicksand.admin)

  • Trace: /vqs debug [on|off] (self) or /vqs debug <player> [on|off|toggle] (admin)

  • Bypass: grant vexalquicksand.bypass to exempt a player from quicksand

Enjoy smoother, more controllable quicksand gameplay! If you encounter issues, enable debug: true in config.yml and/or use /vqs debug on the affected player to capture trace logs in console.

PreviousVexal Super SpongesNextVexal Ping Compass

Last updated