> For the complete documentation index, see [llms.txt](https://docs.mantic.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mantic.dev/manticdarkzone.md). # ManticDarkzone Beginner-friendly ManticDarkzone installation, commands, configuration, editor, and user guide. ManticDarkzone is a Spigot plugin for creating mob-spawning zones with custom mobs, rewards, a reward shop, portals, and player restrictions. * **New to the plugin?** Start with [Quick start](#quick-start). * **Need every setting explained?** See the [full ManticDarkzone guide](https://docs.mantic.dev/manticdarkzone) and its [configuration reference](https://docs.mantic.dev/manticdarkzone/config-files). * **Need the plugin download?** Visit the [ManticDarkzone store page](https://www.mantic.dev/product/manticdarkzone). ## What you can do * Create rectangular areas where selected mobs spawn. * Give each mob type its own name, health, effects, equipment, and rewards. * Override mob settings for one zone without changing that mob's defaults elsewhere. * Trade tagged mob rewards in a configurable shop. * Create portals with selected entrance corners and a destination. * Control commands, PvP, ender pearls, and flight in configured worlds and zones. * View player kill totals on a leaderboard and expose them through PlaceholderAPI. ## Requirements * A Spigot-compatible Minecraft server. ManticDarkzone supports Minecraft versions from 1.8 through the latest version. Some entity and item options depend on the server version. * **ManticLib** installed beside ManticDarkzone. Use the compatible ManticLib release provided for your ManticDarkzone version. * Optional integrations: Multiverse-Core, DeluxeCombat, PlaceholderAPI, and CombatLogX. Install these only if your server uses their related features. ## Quick start 1. Install ManticLib and ManticDarkzone in your server's `plugins` folder. Restart the server; do not use `/reload` to install a plugin. 2. On first start, ManticDarkzone creates its configuration folder at `plugins/ManticDarkzone/`. 3. Claim your ManticDarkzone license key using the instructions provided with your purchase. Open `plugins/ManticDarkzone/config.yml`, put the claimed key in the `license` setting, and keep the key private. Use your own key in place of this placeholder: ```yaml license: "" ``` 4. In the same `config.yml`, find the world where restricted Darkzone gameplay should happen and set its exact loaded name as `darkzone-world-name`. This setting is for player restrictions; it does not define mob spawn areas. 5. Restart the server to load the license and configuration changes. 6. Join that world and run `/mdz zones`. Choose **Create a zone**, enter a unique name, then select two opposite block corners. You can click the blocks or stand at each corner and use `/mdz zones pos1` and `/mdz zones pos2`. 7. Choose which mobs can spawn, set the mob limit, and save. Include solid ground and enough room above it for mobs. 8. Test the area with a regular player account. Mobs spawn only in a configured zone's world, in loaded chunks, when a player is in that world and the zone has room for another mob. `/mdz zones` is player-only. The default permissions are listed under [Commands and permissions](#commands-and-permissions). ## Configuration files All files are inside `plugins/ManticDarkzone/` unless a row shows a subfolder. | File | What it controls | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.yml` | World restrictions, permissions, command allow/block lists, portals, shop toggle, and ignored regions. | | `commands.yml` | Aliases for `/manticdarkzone`, `/darkzoneshop`, and `/portal`. | | `messages.yml` | Messages shown to players. | | `darkzone-mobs.yml` | Global spawn timing, mob limits, targeting, damage, and reward mode. | | `zones.yml` | Zone worlds and bounds, mob mix, per-zone limits, PvP, command rules, and optional mob overrides. You can create or edit zones in game with `/mdz zones`. | | `portals.yml` | Portal entrance corners and destinations. | | `mobs/.yml` | Default name, health, effects, equipment, and rewards for each mob type. For example, `mobs/zombie.yml`. | | `menus/leaderboard.yml` | Kill leaderboard display and layout. | | `menus/darkzoneshop.json` | Shop layout, items, trade prices, and purchase commands. | The YAML files use lowercase hyphenated keys, such as `spawn-frequency-seconds` and `mob-settings`. JSON shop fields keep the camelCase spelling required by that file's format, such as `dropAmountToTrade`. Use spaces for YAML indentation, never tabs. Quote text that begins with `&` or `#`. Use `[]` for an empty list and `{}` for an empty map. JSON does not allow comments. ### Example: a zone You can create or edit zones in game with `/mdz zones`; use its corner selection and save controls instead of editing `zones.yml` by hand. The example below is for servers that prefer manual YAML. Replace the world and coordinates with your own. Bounds are inclusive block coordinates; an all-zero region is one position, not a whole world. ```yaml # Each entry defines an area where darkzone mobs can spawn. # Use a different zone-id for every zone and the exact loaded world name. zones: - zone-id: graveyard world-name: world min-x: 0 min-y: 60 min-z: 0 max-x: 40 max-y: 90 max-z: 40 allow-commands: true allow-pvp: true mobs: - ZOMBIE:0.7 - WOLF:0.3 max-mobs: 20 mobs-bound-to-area: true spawn-frequency-seconds: 0 # Optional per-mob overrides. Remove an entry to use that mob file's defaults. mob-settings: - mob: ZOMBIE inherit-name: false name: '&2Grave Walker' inherit-health: true inherit-potion-effects: false potion-effects: SPEED: 0 inherit-hand: true inherit-helmet: false helmet: material: LEATHER_HELMET name: '&aExplorer Hood' lore: [] enchants: {} colour: '#55FF55' durability: 0 inherit-chestplate: true inherit-leggings: true inherit-boots: true ``` In YAML, mob mix values are shares: `1` means 100%, `0.5` means 50%, and `0.01` means 1%. The zone builder asks for ordinary percentages instead. A zone spawn frequency of `0` uses the global value in `darkzone-mobs.yml`. With `mobs-bound-to-area: true`, mobs can wander throughout the whole zone while idle and target players inside that zone. If they leave, they stop chasing and walk toward separate nearby points inside the boundary. They can resume normal wandering after returning. Keep terrain walkable: walls or cliffs can block the route, and the plugin does not teleport mobs or load chunks for them. Set this option to `false` if mobs may roam outside the zone. ### Example: a mob reward This illustrates the shape of a reward entry. ```yaml # The id is used by the shop when this reward is currency. drops: - id: darkzone-shard display-name: '&bDarkzone Shard' display-lore: - '&7A reward from the graveyard' material: EMERALD lowest-amount: 1 highest-amount: 2 weight: 0.25 always-drop: false commands: [] ``` With `use-chances-instead-of-weights: true`, `weight: 0.25` gives this reward a 25% chance. When the setting is false, positive weights are relative to the other rewards and a reward is selected at most once. `max-drops` limits ordinary rewards; `always-drop: true` rewards are guaranteed in addition to that limit. A `max-drops` value of `0` disables ordinary rewards; `-1` means no limit. The exact materials and mob types available depend on the server version. ## Configure the shop The shop file is `menus/darkzoneshop.json`. Its field names are camelCase because this file is JSON and the plugin reads those exact names. Every row in `layout` must contain nine characters; an item's `key` determines its slot. This example trades five tagged `darkzone-shard` rewards for one diamond: ```json { "title": "Darkzone Shop", "layout": [" d "], "shopItems": [ { "displayName": "&bDiamond", "lore": ["&7Cost: 5 Darkzone Shards"], "material": "DIAMOND", "key": "d", "commands": ["give {player} diamond 1"], "dropIdToTrade": "darkzone-shard", "dropAmountToTrade": 5 } ] } ``` Create a reward with the matching `id` and an item `material` first. Only tagged ManticDarkzone rewards count as currency; changing an item's display name does not turn it into currency. Shop commands run from the console after payment, without a leading slash. The plugin replaces `{player}` with the buyer's name. ## Example: ignored regions `config.yml` can exempt selected areas from global player restrictions. Both corners must be in the same world: ```yaml # Areas where players can use commands normally. Use [] if you do not need any. # These corners also exempt the area from pearl and flight restrictions. ignored-regions: - corner-one: world: world x: 0 y: 0 z: 0 yaw: 0 pitch: 0 corner-two: world: world x: 20 y: 100 z: 20 yaw: 0 pitch: 0 ``` This is a partial example of an ignored region. Both corners must be in the same world. Use the zone creator in game for zones; this setting is for areas excluded from global player restrictions. ## Commands and permissions The default main command is `/manticdarkzone`, with aliases `/mdz` and `/darkzone`. `/darkzoneshop` also has aliases `/mdzshop` and `/dzshop`, and `/portal` has alias `/portals`. All `/mdz` subcommands except `/mdz editor` require `mantic.darkzone.basecommand` plus any additional permission shown below. Permission values and aliases can be changed in the configs. | Command | What it does | Additional default permission | | ---------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------ | | `/mdz` | Show help. | `mantic.darkzone.basecommand` | | `/mdz editor` | Open the in-game configuration editor. | `manticdarkzone.editor` | | `/mdz zones` | Open the zone builder. Players only. | `mantic.darkzone.zones` | | `/mdz reload` | Reload supported files and clear active Darkzone mobs. | `mantic.darkzone.reload` | | `/mdz forcespawn ` | Spawn a mob at your location. Players only. | `mantic.darkzone.forcespawn` | | `/mdz resettargets` | Clear targets from tracked mobs. | `mantic.darkzone.resettarget` | | `/mdz clear` | Remove tracked Darkzone mobs. | `mantic.darkzone.mobclear` | | `/mdz givedrop ` | Give a configured reward to an online player. | `mantic.darkzone.givedrop` | | `/mdz top` | Open the kill leaderboard. Players only. | `mantic.darkzone.top` | | `/darkzoneshop [player]` | Open the shop, or open it for a player. | `manticdarkzone.shop`; add `manticdarkzone.admin` to open it for someone else. | | `/portal create ` | Start selecting two entrance corners. | `manticdarkzone.admin` | | `/portal setdestination ` | Set the destination to your current location and facing direction. | `manticdarkzone.admin` | | `/portal list [page]` | List saved portals. | `manticdarkzone.admin` | | `/portal visualise ` | Preview a portal boundary. | `manticdarkzone.admin` | | `/portal remove ` | Delete a portal. | `manticdarkzone.admin` | ## In-game configuration editor Run `/mdz editor` in the game as a player. It is player-only and uses `manticdarkzone.editor` (default: operators). This command has its own permission: it does not require `mantic.darkzone.basecommand`. The first screen has these sections: | Editor section | What it edits | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | **General** | `config.yml`, including world restrictions, permissions, portals, shop enablement, and ignored regions. | | **Commands** | `commands.yml` aliases. | | **Messages** | `messages.yml` player-facing text. | | **Mob settings** | `darkzone-mobs.yml` global spawn and combat settings. | | **Mob profiles** | Individual `mobs/.yml` files for mob names, health, effects, equipment, and rewards. | | **Darkzone shop** | `menus/darkzoneshop.json`. The editor previews the layout and lets you click an item or an available empty slot. | | **Zone editor** | Opens the separate `/mdz zones` zone builder. See [In-game zone builder](#in-game-zone-builder). | | **Portal editor** | Appears when portals are enabled and opens the `/portal` commands. | To customize the leaderboard, edit `menus/leaderboard.yml` and restart the server to apply layout changes. Portals are managed with `/portal`, and spawn zones are managed with `/mdz zones`. ### How to edit a setting 1. Click a file or section, then click through nested settings until you reach the value you want. 2. Boolean settings toggle when clicked. For other single values, the menu closes and asks you to enter the new value in chat. The editor consumes that chat message while it is waiting for input. 3. Type `cancel` to leave a chat prompt without changing the value. If a value is invalid, read the error; the editor may keep the prompt open or return to the setting so you can reopen it. 4. Lists and maps open their entries. Use **Add entry** to add one. To delete an entry, open it, choose **Remove entry**, then confirm or go back. 5. Use the back button to return to the previous menu. Setting descriptions from the generated YAML comments appear in the menu, including descriptions on nested settings. The editor saves changes as you make them; there is no separate Save button for these config files. Saving reloads plugin settings and clears active Darkzone mobs so new settings can take effect. Changes to command aliases or command permissions require a server restart. ### Editing mob equipment Open **Mob profiles**, choose a mob, and select **Equipment Builder**. Choose the hand, helmet, chestplate, leggings, or boots slot, then select a compatible item from your inventory. This copies the item into the mob profile; it does not take the item from your inventory. You can then edit item details such as its name, lore, enchantments, leather colour, and model or durability value in the nested settings. ### Reviewing editor activity Players with `manticdarkzone.editor.logs` (default: operators) see an **Activity log** button. It shows recent editor opens and changes, includes the player and time, and can be filtered by player. The activity view displays the newest 1,000 entries from `plugins/ManticDarkzone/config-editor.log`. Entries are also written to the server log. ## In-game zone builder The zone builder is separate from `/mdz editor`. It requires both `mantic.darkzone.basecommand` and `mantic.darkzone.zones`; it is player-only. `/mdz zone` is an alias for `/mdz zones`. | Command | What it does | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `/mdz zones` | Browse saved zones or start creating one. | | `/mdz zones create ` | Start a new zone draft. Names can use 1–32 letters, numbers, `_`, or `-`; `zoneless` is reserved. | | `/mdz zones edit ` | Open a saved zone as a draft. | | `/mdz zones pos1` and `/mdz zones pos2` | Set the first or second corner to your current position while selecting bounds. You can also click the two corner blocks. | | `/mdz zones cancel` | Discard the current draft. | In a zone's menu, you can set its corners, spawn interval, mob limit, mob mix, per-mob name/health/effects/equipment overrides, PvP, command access, and whether mobs stay within the zone. Set a zone's spawn interval to `0` to use the global interval from `darkzone-mobs.yml`. The editor asks for mob shares as percentages and balances the mix automatically. Set a share to `0` to remove that mob from the mix. Use **Preview boundaries** to check the area before saving. Zone edits are drafts until you click **Save zone**. Saving writes `zones.yml` and applies the change immediately. When you edit an existing zone, its tracked mobs are cleared so future spawns use the updated settings. **Discard draft** or `/mdz zones cancel` drops your unsaved changes. When entering a value in chat, `cancel` only backs out of that prompt. An inactive draft expires after 10 minutes. The zone command permission can be changed in `config.yml`. Unlike `/mdz editor`, `/mdz zones` also requires the main command permission. ## Player restrictions and portals * `darkzone-world-name` in `config.yml` is the exact world used for global command, ender-pearl, and flight restrictions. Spawn zones are configured separately in `zones.yml`; create or edit them in game with `/mdz zones`. * With `should-block-all-commands: true`, only commands in `allowed-commands` work. With `false`, commands in `blocked-commands` are denied instead. Matching is case-insensitive and uses prefixes, so `f` also matches `fly`. Allowed prefixes take priority. * `manticdarkzone.bypass` bypasses command, ender-pearl, and flight restrictions. `manticdarkzone.flightdisabler.bypass` bypasses flight disabling only. * `ignored-regions` exempts selected areas from command, ender-pearl, and flight restrictions. It does not create a mob spawn zone. Portal rules still apply separately. * Set `must-be-out-of-combat-to-use-portal: true` to block portal use while in combat. The combat check supports DeluxeCombat and CombatLogX when installed. To create a portal, run `/portal create entrance`, then click two opposite blocks for the entrance. Stand where players should arrive, face the intended direction, and run `/portal setdestination entrance`. Use `/portal visualise entrance` to check the boundary. ## PlaceholderAPI With PlaceholderAPI installed, other plugins that support PlaceholderAPI can use: | Placeholder | Result | | ------------------------------- | --------------------------------------- | | `%manticdarkzone_killed%` | Formatted kill count. | | `%manticdarkzone_killed_raw%` | Kill count as an integer. | | `%manticdarkzone_killed_short%` | Abbreviated kill count, such as `1.2k`. | Reward and purchase commands use `{player}` for the recipient's name. ## Leaderboard Player kills of Darkzone mobs are counted for `/mdz top` (also `/mdz lb` and `/mdz leaderboard`). The command opens a player GUI and requires the permission configured as `darkzone-top-base-permission` in `menus/leaderboard.yml`. Set `enabled: false` to turn the leaderboard off. The same file controls the title, row format, one-to-six-row inventory layout, player icons, and decorative items. Each layout row must be exactly nine characters; its keys map the row's slots to leaderboard items. `fill-key` marks ranked-player slots, `you-key` marks the viewing player's slot, and decorative item keys must also appear in the layout. Edit this file and restart the server to apply changes. ## Plugin API for developers Other Bukkit plugins can use the public `me.fullpage.manticdarkzone.api.Mob` enum to look up configured mob types and spawn them. `Mob.fromString("ZOMBIE")` returns the matching type or `null`; check `mob.isAvailable()` before spawning because availability depends on the server version. `mob.spawnWithoutZone(location)` spawns a tracked mob outside a configured zone. `Mob.spawn(zone, mob, location)` creates one for a specific zone. Both use that mob's configured profile. ManticDarkzone also provides Bukkit events under `me.fullpage.manticdarkzone.api.events`: | Event | When it fires | Cancellation effect | | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `DarkzoneMobHitEvent` | A player and a tracked Darkzone mob interact in combat. The event exposes the player and the mob through `getHit()`. | Cancels that combat damage. | | `DarkzoneMobKillEvent` | A player kills a tracked Darkzone mob. The event exposes the death event, killed entity, and configured reward list. | Skips the plugin's configured rewards, kill message, XP grant, and kill-count update. | Register these with Bukkit's normal event listener system. A listener that uses this API must compile against ManticDarkzone's classes and have ManticDarkzone installed on the server. ## Reloading and restarting `/mdz reload` reloads `config.yml`, `messages.yml`, `darkzone-mobs.yml`, the shop file, and `portals.yml`. It recalculates spawn areas and removes active Darkzone mobs. Use a full server restart after manually editing `zones.yml`, mob profile files, leaderboard settings, command aliases, or command permissions. Saving a zone through the in-game builder applies it immediately. ## Download and update the plugin ManticDarkzone is a commercial plugin distributed as a ready-to-install jar. Purchase it from the [ManticDarkzone product page](https://www.mantic.dev/product/manticdarkzone); customers can download the jar and available updates through their purchase downloads. To update, back up `plugins/ManticDarkzone/`, replace the old plugin jar with the updated jar, keep the compatible ManticLib plugin installed, and restart the server. Do not use `/reload` to install or update a plugin. ## Troubleshooting **No mobs spawn** * Use `/mdz zones` in game to inspect or edit the spawn zone; you do not need to change `zones.yml` by hand. * Confirm `enabled: true` in `darkzone-mobs.yml` and set the zone's `max-mobs` above 0. * Check `world-name` exactly matches the loaded world and the zone's mob list is not empty. * Make sure at least one player is in that world, the area is in loaded chunks, the bounds include solid ground, and there is room above the ground. * Check the server log for YAML errors. Use spaces for indentation, not tabs. **The zone does not cover the area I expected** The two corners define a rectangular volume. All-zero coordinates select only one position. Use `/mdz zones` to reselect and preview the corners in game, or set X, Y, and Z bounds for opposite corners in `zones.yml`. Include the height where mobs should stand. **The shop does not accept an item** Shop currency must be a tagged ManticDarkzone reward, not an ordinary item with a renamed display name. Match `dropIdToTrade` in `menus/darkzoneshop.json` to the reward's `id`, use an item material, and check that the player has the configured amount. **The server rejects a material, mob, or effect** Some values are available only on certain server versions. Use values supported by your server and select mob types reported as available by `/mdz forcespawn` tab completion. ## More help See the [ManticDarkzone guide](https://docs.mantic.dev/manticdarkzone), [configuration reference](https://docs.mantic.dev/manticdarkzone/config-files), and [FAQ](https://docs.mantic.dev/manticdarkzone/frequently-asked-questions-faq). If you report a problem, include the plugin version, server version, the relevant non-sensitive config section, and the error from your server log. Remove private license values and server credentials before sharing configuration.