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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vexalstudios.com/minecraft-plugins/vexal-quicksand-free.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.