> For the complete documentation index, see [llms.txt](https://docs.vexalstudios.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vexalstudios.com/minecraft-plugins/vexal-quicksand-free.md).

# Vexal Quicksand - Free

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.