**Author:** RajaAditya **Website:** [rajaaditya.my.id](https://rajaaditya.my.id) **Version:** 1.0.1 **API:** Paper 1.21.x --- ## About SVJails is a self-contained jail/prison management plugin — no dependency on WorldGuard or any external region plugin. Punishments are tracked per-player with a countdown timer that runs asynchronously, so large numbers of jailed players don't add load to the main server thread. While jailed, players are restricted from a configurable set of escape vectors (commands, block interaction, teleport items, buckets, boats/minecarts) and are automatically returned to their cell if they log out and back in before their sentence ends. As of **v1.0.1**, SVJails supports **multiple jail locations**. Admins can register any number of named cells and either assign a player to a specific one manually, or let the plugin pick automatically — favoring empty cells so prisoners don't get stacked on top of each other. --- ## Features ### Command System - `/jail [jails]` — sentences a player and starts their countdown. - If `[jails]` is **omitted**, a jail location is picked **automatically**, prioritizing cells with no current occupant. If every cell is occupied, one is picked at random as a fallback. - If `[jails]` is **specified** (must match a name registered via `/setjail`), the player is sent to that exact cell — **manual selection always works, even if that cell already has someone in it.** - `/unjail ` — force-releases a player and returns them to where they were before being jailed - `/setjail [nama]` — saves your current standing position as a named jail cell (defaults to `"default"` if no name given). Aliased as **`/setjails`**, so cells can be created like `/setjails 1`, `/setjails 2`, `/setjails vip`, etc. - `/jailcheck [player]` — checks remaining sentence time, reason, issuing admin, and **which cell** they're in; players can check their own status by omitting the argument - `/svjails reload` — reloads `config.yml` and `messages.yml` without a restart - Tab-completion: - `/jail`: online player names (arg 1), duration presets `10s / 30m / 1h / 6h / 1d / 3d / 7d` (arg 2), common reason presets (arg 3), and **registered jail names** (arg 4, optional) - `/setjail` / `/setjails`: suggests existing jail names plus `1`, `2`, `3`, `default` as quick starting points ### Multi-Jail Selection Logic | Scenario | Result | |---|---| | `/jail Steve 1h Griefing` (no `[jails]` arg) | Auto-picks a random **empty** cell. Won't place Steve into an occupied cell unless all cells are full. | | `/jail Steve 1h Griefing 2` (`[jails]` = `2`) | Steve goes to cell `2` regardless of whether it's already occupied. | | `/jail Steve 1h Griefing unknownname` | If `unknownname` doesn't match any registered cell, it's treated as part of the reason text instead — and a cell is auto-picked. | | No cells registered at all | `/jail` fails with the "no jail location" message; register one with `/setjail` first. | Each sentence remembers which specific cell it was assigned to. If a jailed player logs out and back in, they're returned to **that same cell** (not always `"default"`) — even across restarts, since the cell name is now part of the persisted sentence data. ### Anti-Escape System - **Command blocking** — any command not on the configurable whitelist is blocked while a player is jailed (`whitelisted-commands` in `config.yml`) - **Block interaction blocking** — breaking and placing blocks is disabled while jailed - **Bucket blocking** — emptying any bucket (water, lava, powder snow, etc.) is blocked while jailed, since bucket placement doesn't go through the normal block-place event - **Vehicle blocking** — placing boats, chest boats, and minecarts is blocked while jailed (checked on interaction, before the entity is even created) - **Teleport-item blocking** — Ender Pearl and Chorus Fruit teleportation are cancelled while jailed (each independently toggleable) - **Jail-on-login** — if a player logs out while jailed, they're teleported straight back to their assigned cell on rejoin, preventing logout as an escape method - **Bypass permission** — `svjails.bypass` exempts a player (typically staff testing the system) from every anti-escape restriction above ### Persistence - Sentences persist across restarts via a YAML data store (`jaildata.yml`) — nothing is lost on a crash or reboot - Stored per player: UUID, remaining time (seconds), reason, issuing admin, previous location (for restoring on release), and **assigned jail cell name** - Storage is built behind a `StorageProvider` interface, so a MySQL-backed implementation can be added later without touching command or listener code — useful if a future version needs to synchronize jail status across multiple servers on a proxy network ### Timer & Scheduler - Countdown runs on an **async repeating task**, decrementing every jailed player's remaining time without blocking the main thread - The moment a sentence hits zero, execution switches back to the **main thread** (Bukkit's API isn't safe to call from async code) to perform the actual teleport and broadcast - Auto-release on expiry teleports the player back to their location from before they were jailed ### Integration & UI - **PlaceholderAPI** (soft-depend): `%svjail_timeleft%`, `%svjail_reason%`, `%svjail_jailedby%`, `%svjail_status%` - **`messages.yml`** — every player-facing message (prefix, jail/unjail notifications, blocked-action warnings, command feedback) is fully editable without recompiling, with `&` legacy and `&#RRGGBB` hex color support, now including a `{jail}` placeholder wherever the assigned cell name is relevant --- ## Dependencies | Plugin | Required | Purpose | |--------|----------|---------| | [PlaceholderAPI](https://github.com/PlaceholderAPI/PlaceholderAPI) | Optional (`softdepend`) | Exposes `%svjail_...%` placeholders for scoreboards, tab lists, etc. | No other dependencies — SVJails does not require WorldGuard, Vault, or any economy/region plugin to function. --- ## Installation 1. Optionally install **PlaceholderAPI** if you want `%svjail_...%` placeholders elsewhere on your server 2. Place `SVJails-1.0.1.jar` into your `plugins/` folder and start the server once to generate `config.yml`, `messages.yml`, and `jaildata.yml` 3. Stand where you want a jail cell to be and run `/setjail` (or `/setjail ` / `/setjails ` for a named cell). Repeat for as many cells as you want — e.g. `/setjails 1`, `/setjails 2`, `/setjails 3` 4. Adjust `whitelisted-commands`, anti-escape toggles, and time-unit aliases in `config.yml` to taste 5. Use `/svjails reload` to apply config/message changes without restarting --- ## File Structure ``` plugins/SVJails/ ├── config.yml # Jail locations (multi), storage type, anti-escape toggles, time-unit parsing ├── messages.yml # All plugin messages, fully editable └── jaildata.yml # DO NOT edit manually — active/queued sentence data, incl. assigned cell ``` --- ## Configuration ### config.yml ```yaml storage: type: YAML mysql: host: localhost port: 3306 database: svjails username: root password: "" table-prefix: "svjails_" timer: update-interval: 20 # Setiap key di bawah "jails" adalah satu lokasi sel yang bisa dipilih # secara manual (/jail ) atau otomatis # (tanpa argumen nama — dipilih acak, prioritas yang masih kosong). jails: default: world: world x: 100.5 y: 64.0 z: 200.5 yaw: 0.0 pitch: 0.0 1: world: world x: 150.5 y: 64.0 z: 200.5 yaw: 0.0 pitch: 0.0 2: world: world x: 200.5 y: 64.0 z: 200.5 yaw: 0.0 pitch: 0.0 whitelisted-commands: - "/jailcheck" - "/msg" - "/spawn" - "/help" anti-escape: block-break: true block-place: true block-teleport-items: ender-pearl: true chorus-fruit: true jail-region-radius: 5 time-units: second: [ "s", "sec", "detik" ] minute: [ "m", "min", "menit" ] hour: [ "h", "jam" ] day: [ "d", "hari" ] time-format: day: "d" hour: "h" minute: "m" second: "s" separator: " " placeholderapi: enabled: true save-previous-location: true debug: false config-version: 1 ``` > **Note:** `storage.type` currently only ships with a YAML implementation in v1.1. The `mysql:` block is reserved for a future `MySQLStorageProvider` and has no effect yet. `jail-region-radius` is likewise reserved for a future spatially-scoped anti-break/place mode — as of v1.1, anti-break/place applies globally to any jailed player, not just within a radius of the cell. Jail names under `jails:` can be any string (`default`, `1`, `2`, `vip`, etc.) — there's no hard limit on how many cells you register. **`time-units` vs `time-format`:** these serve opposite purposes. `time-units` defines the aliases accepted when an admin **inputs** a duration (`/jail Steve 2jam ...` and `/jail Steve 2h ...` both resolve to "hour"). `time-format` defines how a stored duration is **displayed** back to players (e.g. via `/jailcheck` or `%svjail_timeleft%`). Changing one has no effect on the other. ### messages.yml ```yaml prefix: "&8[&cSVJails&8] &r" jail: success-admin: "&aBerhasil memenjarakan &e{player} &aselama &e{time} &akarena: &7{reason} &a(sel: &e{jail}&a)" already-jailed: "&cPlayer {player} sedang dipenjara." invalid-time-format: "&cFormat waktu salah. Contoh: 1d, 2h, 30m, 10s" no-jail-location: "&cBelum ada lokasi jail! Gunakan /setjail terlebih dahulu." target-notify: - "&8&m----------------------------------" - "&cKamu telah dipenjara!" - "&7Alasan: &f{reason}" - "&7Durasi: &f{time}" - "&7Admin: &f{admin}" - "&7Sel: &f{jail}" - "&8&m----------------------------------" anti-escape: command-blocked: "&cKamu tidak bisa menggunakan command itu selagi dipenjara!" block-break-blocked: "&cKamu tidak bisa merusak block selagi dipenjara!" block-place-blocked: "&cKamu tidak bisa menaruh block selagi dipenjara!" teleport-blocked: "&cKamu tidak bisa teleportasi selagi dipenjara!" timer: time-up-broadcast: "&e{player} &7telah selesai menjalani masa hukuman." ``` *(abbreviated — see the bundled file for the full message set, including `unjail`, `setjail`, `jailcheck`, and `general` sections)* Every message supports `&` legacy color codes and `&#RRGGBB` hex codes. Missing keys introduced by a future update are merged in automatically from the bundled defaults, preserving existing customizations — same behavior as RA-ExcellentMenus. The new `{jail}` placeholder is available in `jail.success-admin`, `jail.success-broadcast`, and `jail.target-notify` and resolves to the cell name the player was actually sent to. --- ## Commands | Command | Description | Usage | |---------|-------------|-------| | `/jail` | Sentences a player to jail for a given duration, optionally to a specific cell | `/jail [jails]` | | `/unjail` | Force-releases a jailed player | `/unjail ` | | `/setjail` (alias `/setjails`) | Saves your current position as a named jail cell | `/setjail ` | | `/jailcheck` | Checks remaining sentence time for a player (or yourself) | `/jailcheck [player]` | | `/svjails reload` | Reloads config and messages | `/svjails reload` | --- ## Permissions | Permission | Default | Description | |------------|---------|-------------| | `svjails.jail` | `op` | Use `/jail` | | `svjails.unjail` | `op` | Use `/unjail` | | `svjails.setjail` | `op` | Use `/setjail` / `/setjails` | | `svjails.jailcheck` | `op` | Use `/jailcheck` | | `svjails.admin` | `op` | Use `/svjails reload` | | `svjails.bypass` | `op` | Exempt from all anti-escape restrictions | --- ## PlaceholderAPI Placeholders | Placeholder | Description | |-------------|--------------| | `%svjail_timeleft%` | Formatted remaining sentence time, or "Tidak dipenjara" if not jailed | | `%svjail_reason%` | The reason given when the player was jailed | | `%svjail_jailedby%` | Name of the admin who issued the sentence | | `%svjail_status%` | "Dipenjara" or "Bebas" | --- ## Changelog ### v1.0.1 - Added multi-location jail support — register any number of named cells with `/setjail ` / `/setjails ` - `/jail` now accepts an optional `[jails]` argument to manually pick a cell; manual picks always succeed even if the cell is occupied - When no cell is specified, SVJails auto-selects a random **unoccupied** cell, falling back to any cell if all are full - Sentence data now stores which cell a player was assigned to, so relog and restart correctly return them to the right cell instead of always `"default"` - `{jail}` placeholder added to relevant `messages.yml` entries ### v1.0.0 - Initial release --- ## License Developed by **RajaAditya** — [rajaaditya.my.id](https://rajaaditya.my.id) This plugin is **closed source**. Redistribution without permission is prohibited.