The official documentation for all UltraPlugins.
Explore setup guides, file configurations, commands, and permissions using the sidebar. If you need help, encounter an issue, or want to suggest new features, join our official Discord community.

UltraRituals turns altar activation into custom encounters and events. Create rituals that summon a mob, progress through successive combat phases or execute commands. Combine configurable offerings, MythicMobs and EliteMobs pools, activation delays and audiovisual effects to build your own ritual experience.
Build rituals around configurable altars and offerings, or use click-only activation. Customize altar visuals and control the timing before the ritual begins.
Use MythicMobs and EliteMobs entries in the same ritual pool. Assign relative weights to control which encounter is selected when the ritual activates.
Create successive combat phases, with each mob's death unlocking the next encounter. Configure phase recovery time and cooldowns to pace the event.
Create command-only rituals or add event commands to encounters. Customize messages, titles, action bars, sounds and visual effects to give each ritual its own identity.
Requirements, installation and safe updates.
plugins/.| Integration | Required when |
|---|---|
| MythicMobs | A pool contains mythicmobs: entries. |
| EliteMobs | A pool contains elitemobs: entries. |
| PlaceholderAPI | You want ritual placeholders in other plugins. |
| No mob provider | You only use command rituals. |
plugins/UltraRituals/.Migration preserves .bak copies. See Troubleshooting if a ritual references an unavailable world.
| Edition | License |
|---|---|
| Marketplace | Requires an injected BuiltByBit license or a direct-sale key. |
| Personal | Private build without license checks. |
Install only one edition. Do not distribute the generated license/ installation state.
Spigot 1.21 and Purpur 26.3 build 2645 are compilation/test targets. Use the Java runtime required by your server and test your provider versions before updating production.
Find the command for your current editing session.
Permission: ultrarituals.admin (operators by default). Aliases: /rituals and /ultraritual. Use these commands in game.
After /ultrarituals | Action |
|---|---|
create mobs <id> | Create a random-mob ritual. |
create phases <count> <id> | Create 1–100 phases. Count comes before the name. |
create command <id> | Create a command ritual. |
edit <id> | Edit an inactive ritual. |
save | Validate and save; every phase needs mobs. |
leave | Repeat to confirm leaving without saving. |
| Current session | Type-specific suggestions |
|---|---|
command | setcommand |
mobs | setspawn, setmob |
phases | setspawn, setphasemob, addphase, removephase |
| Not editing | Management commands only. |
Shared editing commands remain visible for every type. Arguments for unrelated commands are hidden too.
| Command | Action |
|---|---|
setspawn | Use your current location for mob spawns. |
setmob <provider:mob[:weight],...> | Replace a mobs ritual's pool. |
setphasemob <phase> <pool> | Replace one phase's pool. |
addphase | Append an empty phase. |
removephase <phase> | Remove a phase and renumber later phases. |
setcommand <command> | Set the main action of a command ritual. |
setcooldown <seconds> | Change the cooldown. |
setdelay <seconds> | Change the initial delay. |
setname <name> | Change the display name. |
| Command | Action |
|---|---|
list | List ritual IDs. |
reload | Reload configurations. |
reset <id> | Abort pending work, remove the loaded boss and start cooldown without completion rewards. |
delete <id> | Delete a ritual definition. |
Create a ritual, define its action and place the altars.
Choose one command:
Command example
/ultrarituals create mobs eclipse
/ultrarituals create phases 3 dungeon
/ultrarituals create command eventAll editing commands require ultrarituals.admin (operators by default). Tab completes ritual types and phase counts.
| Type | What to configure |
|---|---|
mobs | Stand at the spawn point, run setspawn, then use setmob. |
phases | Run setspawn, then configure every phase with setphasemob. |
command | Run /ultrarituals setcommand say The event has started. |
/ultrarituals save, then test the ritual outside edit mode.Tip: sneak + right-click an altar as an administrator to open its menu later.
Related: Altars · All commands
Find each file and configuration section.
| File | Contents |
|---|---|
config.yml | Global defaults. |
messages.yml | Plugin feedback. |
guis.yml | Editor buttons and labels. |
rituals/<id>.yml | One ritual's mobs, altars and event configuration. |
animations/<id>.yml | Particle presets. |
.data/ | Runtime state; do not remove to fix configuration errors. |
license/ | Licensed edition state; do not distribute tokens or caches. |
| Section | Reference |
|---|---|
type, display_name | Type and public name. Use setname in edit mode. |
spawn, altars | Locations and item data generated by the editor. |
mobs | Mobs & probabilities |
Phase lists inside mobs | Phases |
command | Main action for command rituals. Set with setcommand. |
settings | Delays & cooldown |
messages | Messages |
commands | Automatic commands |
sounds, activation_effects | Sounds & effects |
Top-level sections can appear in any order. Preserve indentation and the serialized location/item data.
After editing YAML, use /ultrarituals reload. Pending invocations from the old definition are discarded.
Configure offerings, click-only activation and altar visuals.
| Action | Result |
|---|---|
| Place a block in edit mode | Add an altar. |
| Right-click while editing | Open its menu. |
| Sneak + right-click as an administrator | Open its menu outside edit mode. |
| Click an item in your inventory in the menu | Require one of that item. |
| Right-click the Required Item button | Clear the requirement; enable click-only activation. |
| Break an altar while editing its ritual | Remove it from the ritual and delete its displays. |
An empty altar activates with a normal right-click, consumes nothing and skips the item-insertion cinematic. Leave edit mode before testing it.
| Key | Purpose |
|---|---|
scale, y_offset | Item size and height. |
rotation_speed, oscillation_speed | Item rotation and bobbing. |
light | Display brightness (0–15), not a world light source. |
show_inside, show_idle_item | Item visibility inside the block and while waiting. |
use_cinematic | Animate item insertion; does not move the player's camera. |
show_particles | Toggle particle effects. |
waiting_animation, activation_animation | Offering and activation animation IDs. |
summoning_animation, idle_animation | Summoning and idle animation IDs. Use none to disable. |
activation_mode | Display after activation |
|---|---|
DROP | Item drops inside the block. |
FLOAT | Item remains floating. |
HIDE | Item disappears. |
A required offering is consumed in every mode. Keep serialized location and item data generated by the editor.
Mix providers and let relative weights choose the next mob.
One mob is chosen per invocation. Entries can mix both providers.
Command example
/ultrarituals setmob mythicmobs:ECLIPSITA_BOSS:20,elitemobs:Golem:20setmob replaces the whole pool. Separate entries with commas, without spaces.
| Entry | Provider ID |
|---|---|
mythicmobs:Boss:20 | Internal MythicMobs mob ID. |
elitemobs:folder/Golem:20 | EliteMobs custom boss path; .yml is optional. |
| Values | Actual chance |
|---|---|
20, 20 | 50% each |
20, 60 | 25% and 75% |
| No values on any entry | Equal chance for every entry |
0, 20 | Only the second mob can win |
YAML example
type: mobs
mobs:
- 'mythicmobs:ECLIPSITA_BOSS 20'
- 'elitemobs:Golem 20'Merge this fragment into the existing file; keep its other settings.
Weights are preserved in YAML. Phase pools use the same rules.
Build an encounter with successive bosses and recovery time.
Command example
/ultrarituals create phases 2 dungeon
/ultrarituals setspawn
/ultrarituals setphasemob 1 mythicmobs:Guard:70,elitemobs:Golem:30
/ultrarituals setphasemob 2 mythicmobs:FinalBossPlace your altars, configure them and run /ultrarituals save.
No new offerings are needed between phases. The ritual stays busy during recovery.
| Command | Effect |
|---|---|
addphase | Append an empty phase. Configure its mobs before saving. |
removephase <number> | Remove a phase and renumber later phases, including their messages and commands. |
setphasemob <number> <pool> | Replace the selected phase's pool. |
Phase counts range from 1 to 100. At least one phase must remain.
YAML example
type: phases
mobs:
phases:
'1':
- 'mythicmobs:Guard 70'
- 'elitemobs:Golem 30'
'2':
- 'mythicmobs:FinalBoss'Merge this fragment into the existing file; keep its other settings.
Keep the spawn and altar locations generated by the editor. Phase keys must be consecutive, starting at 1.
Related: Delays · Messages · Automatic commands · Sounds
Set the initial wait, phase recovery and cooldown.
YAML example
settings:
cooldown: 60
delay:
initial: 3
between_phases: 5Merge this fragment into the existing file; keep its other settings.
The example above shows where each key belongs: cooldown is inside settings; both delays are inside its delay section.
| Option | YAML key | Value |
|---|---|---|
| Initial wait | initial | Seconds before the first mob/action. -1 uses the global initial delay. |
| Recovery between phases | between_phases | Seconds after a boss dies. Default: 5; 0 disables recovery. |
| Ritual cooldown | cooldown | Seconds before the ritual becomes available. -1 uses the global cooldown; 0 disables it. |
YAML example
ritual:
cooldown: 30
spawn_delay: 3Merge this fragment into the existing file; keep its other settings.
A ritual value of -1 inherits the corresponding global value shown above.
setdelay <seconds> changes the initial delay. setcooldown <seconds> changes the cooldown. Edit between_phases in the ritual YAML.
| Setting | Unit |
|---|---|
| Ritual delays and cooldown | Seconds |
delay <seconds> in command lists | Seconds |
| Last value in a sound entry | Ticks (20 = 1 second) |
During recovery, the phase placeholder keeps the last started phase. Before the first spawn it is 0. A phase begins only when its mob spawns successfully.
Choose an event and customize titles, chat and action bars.
Configure messages in each ritual's YAML. Plugin feedback and editor labels belong in messages.yml and guis.yml instead.
All message groups belong inside the messages section.
| Event | Sent when |
|---|---|
altar_activation | One altar activates. |
ritual_activation | The first mob/action starts. |
phases | A numbered phase's mob spawns successfully. |
ritual_completion | The final boss dies, or the command action completes. |
Completion messages are not sent for failed spawns or manual resets.
YAML example
messages:
radius: 50.0
ritual_completion:
title: '&aRitual completed!'
subtitle: ''
action-bar: ''
chat:
- '&aThe ritual %ritual_name% has been completed!'Merge this fragment into the existing file; keep its other settings.
| Field | Purpose |
|---|---|
title, subtitle | Center-screen announcement. |
action-bar | Message above the hotbar. |
chat | List of chat messages. |
radius | Blocks around the spawn, or first altar, in the same world. |
Empty fields and an empty chat: [] disable notices. Use a nonnegative radius; -1 is not a server-wide broadcast.
YAML example
messages:
phases:
'1':
title: '&6Phase %phase%/%total_phases%'
subtitle: '&7Defeat the guardian'
action-bar: ''
chat: []
'2':
title: '&cFinal phase'
subtitle: ''
action-bar: '&eDefeat the final boss!'
chat: []Merge this fragment into the existing file; keep its other settings.
Formatting: & color codes and &#RRGGBB hex colors. See Placeholders for supported variables.
Run player or console commands at each ritual event.
Place these lists inside the commands section, as shown in the example.
| Event | YAML list | Runs when |
|---|---|---|
| Ritual started | activation_commands | The initial mob/action starts successfully. |
| Ritual completed | completion_commands | The whole ritual completes successfully. |
| Ritual ready again | reset_commands | Cooldown expires and the ritual becomes available. |
YAML example
commands:
activation_commands:
- 'console_command: say The ritual has started'
completion_commands:
- 'console_command: say All phases completed'
reset_commands:
- 'console_command: say Ritual %ritual_id% is ready again'Merge this fragment into the existing file; keep its other settings.
| Entry | Executed by |
|---|---|
console_command: <command> | Server console. |
command: <command> | Associated player, if still online. |
delay <seconds> | Pause the remaining entries in that list. |
The initial activator is the player who fills the last altar. Later phase actions use the previous boss's killer. Reset actions use the completing player or the administrator who manually reset it.
Use console commands without player variables when no player is guaranteed. Delayed phase commands keep their original phase number.
Inside commands, add a phases section and then the phase number. Each phase has its own lists:
| Event | YAML list | Runs when |
|---|---|---|
| Phase started | activation_commands | That phase's mob spawns. |
| Phase completed | completion_commands | That phase's boss dies. |
YAML example
commands:
phases:
'1':
activation_commands:
- 'console_command: say Phase %phase% started'
completion_commands:
- 'delay 2'
- 'console_command: say First guardian defeated'Merge this fragment into the existing file; keep its other settings.
Assign sounds and effects to ritual events.
Key under sounds | Event |
|---|---|
altar_filled_sounds | An altar accepts an offering/click. |
ritual_activated_sounds | All altars are active. |
summoning_started_sounds | A mob is created. |
spawn_sounds | A mob appears. |
phase_started_sounds | Any phase mob appears, including phase 1. |
death_sounds | A ritual boss dies. |
reset_sounds | The ritual returns to ready state. |
YAML example
sounds:
phase_started_sounds:
- 'BLOCK_BEACON_ACTIVATE:1.0:1.0:0'Merge this fragment into the existing file; keep its other settings.
Entry format: SOUND:VOLUME:PITCH:DELAY. Delay is in ticks (20 = 1 second). Sounds play at the spawn location or the relevant altar.
YAML example
activation_effects:
radius: 15.0
duration: 10
effects:
- 'SPEED:2'Merge this fragment into the existing file; keep its other settings.
Effects apply to nearby players when all altars activate. duration is in seconds; SPEED:2 means Speed level 2.
Related: Animations
Resolve common issues and migrate older rituals.
| Problem | Check |
|---|---|
| Mob does not appear | Provider is enabled and the ID/path exists. Check the console's spawn error. |
| Altar opens its menu instead of activating | Leave edit mode; do not sneak while testing. |
| Altar still needs an item | Right-click Required Item in its menu to clear the requirement. |
| Ritual seems stuck after a mob was removed externally | Run /ultrarituals reset <id>. |
| A phase starts without recovery time | An explicit between_phases: 0 disables recovery. Set it to 5. |
Ritual is deferred / unknown world | Load the referenced world, then run /ultrarituals reload. |
Old particle Float error | Replace the JAR with the latest 1.0.5 build and restart. |
| Old key | New key |
|---|---|
type: mythicmobs or type: elitemobs | type: mobs with provider-qualified entries. |
mob | mobs list. |
Root activation_commands, completion_commands | Lists inside commands. |
Mob lists inside the old phases section | Numbered phase lists inside mobs. |
spawn_delay inside settings, or at the top level | initial inside the new delay group in settings. |
Migration keeps .bak copies. Existing new-format values take precedence.
Earlier builds could lose locations when their world was unavailable. Current builds defer that ritual and preserve its file.
altars and spawn sections from its .bak, preserving newer settings./ultrarituals reload if the world loaded after the plugin.Never delete .data/ or license installation files as a configuration fix.
Active boss UUIDs and phase numbers are saved in .data/ritual_data.yml. Pending invocations interrupted by reload/restart are not resumed. Reset the ritual if another plugin removes a boss without a death event.
Choose a preset or build a reusable particle animation.
Open an altar's editor and choose an animation for its waiting, activation, summoning or idle state. Select none to disable an animation.
Presets are stored in plugins/UltraRituals/animations/. Edit their YAML, then run /ultrarituals reload.
| Preset | Shape | Particle |
|---|---|---|
explosion | Burst | FLAME |
circle | Rotating ring | SOUL_FIRE_FLAME |
helix | Double helix | WITCH |
vortex | Vortex | DRAGON_BREATH |
orbit | Orbiting particles | GLOW |
wave | Waving ring | CHERRY_LEAVES |
halo | Halo | END_ROD |
heart | Heart | HEART |
dna | DNA strands | SCRAPE |
atom | Atom | ELECTRIC_SPARK |
square | Square | HAPPY_VILLAGER |
sunbeams | Radial beams | DUST |
smoke | Vortex | SMOKE |
shockwave | Expanding ring | DUST |
sphere_explosion | Expanding sphere | SMOKE |
Save this example as animations/custom_ring.yml. After reloading, choose custom_ring in the altar menu.
YAML example
effects:
- effect_type: CIRCLE
particle: DUST
color: '#FF334F'
size: 1.0
amount: 20
spread: 0.0
radius: 1.2
height: 1.0
speed: 1.0Merge this fragment into the existing file; keep its other settings.
| Key | Purpose |
|---|---|
effect_type | Shape: EXPLOSION, CIRCLE, DOUBLE_HELIX, VORTEX, ORBIT, WAVE, HALO, HEART, DNA, ATOM, SQUARE, SUNBEAMS, SHOCKWAVE or SPHERE_EXPANSION. |
particle | Bukkit particle name available on the running server. |
amount | Particle count; how the count is used depends on the shape. |
spread | Scatter for burst effects. |
radius, height | Horizontal radius and vertical position/extent, depending on the shape. |
speed | Movement speed. |
color | Hex color for particles that support it. |
size | Dust size or power for dragon-breath/spell particles. |
sound | Optional Bukkit sound name. |
Add another entry to the same effects list to combine shapes. Keep the same indentation for each entry.
YAML example
effects:
- effect_type: CIRCLE
particle: SOUL_FIRE_FLAME
amount: 20
radius: 1.2
height: 0.2
speed: 1.0
- effect_type: HALO
particle: END_ROD
amount: 20
radius: 0.8
height: 1.8
speed: 1.0Merge this fragment into the existing file; keep its other settings.
Particle data is adapted to the running API. Block/item particles use STONE; vibration/trail particles use a short upward target. Unsupported data types are skipped with a warning.
Related: Altars · Sounds & effects
Use ritual values in messages and other plugins.
| Variable | Meaning |
|---|---|
%player% | Associated player, when available. |
%ritual_id%, %ritual% | Ritual ID. |
%ritual_name% | Public display name. |
%phase%, %total_phases% | Last started phase and total phases. Phase is 0 outside a phase run. |
%active_altars%, %total_altars% | Activated/total altar counts. |
%ritual_active% | Whether the ritual is busy. |
Command lists support %player% (also <player>), %ritual_id%, %phase% and %total_phases%.
Replace <id> with your ritual's ID. PlaceholderAPI is optional.
| Placeholder | Returns |
|---|---|
%ultrarituals_name_<id>% | Public name. |
%ultrarituals_id_<id>% | Ritual ID. |
%ultrarituals_active_<id>% | true while busy, otherwise false. |
%ultrarituals_altars_<id>% | Activated/total, such as 2/4. |
%ultrarituals_active_altars_<id>% | Activated count. |
%ultrarituals_total_altars_<id>% | Total altar count. |
%ultrarituals_cooldown_<id>% | Remaining cooldown seconds. |
%ultrarituals_status_<id>% | Ready, Active, Cooldown or In Progress. |
%ultrarituals_phase_<id>% | Last started phase; 0 outside a phase run. |
%ultrarituals_total_phases_<id>% | Configured phase count. |
UltraFurnaces is the ultimate upgradeable and customizable furnace engine for Spigot/Paper servers. Transform basic item smelting into a full RPG progression system with 8 modular virtual upgrade tracks, dynamic recipes, custom fuels, and stochastic loot drop tables.
Boost cooking speed, fuel efficiency, XP multipliers, Vault currency generation, virtual storage slots, and treasure luck.
Design advanced probabilistic recipes, progressive unlocks based on furnace usage, and native ItemsAdder/ExecutableItems support.
Each placed furnace permanently registers its owner, preventing unauthorized players from breaking it or modifying items, and auto-returns directly to inventory when broken.
Configure custom fuel burn multipliers, infinite fuels, and configurable stochastic treasure loot tables dropping during smelting.
Simple steps to deploy the plugin on your Minecraft server.
Place UltraFurnaces.jar inside the plugins/ folder of your server.
Start or restart your server to automatically generate folder structures and configurations in plugins/UltraFurnaces/.
Install Vault (plus an economy plugin like EssentialsX) if you want furnaces to generate money for owners. Install ItemsAdder or ExecutableItems for custom item recipes.
Global plugin parameters, rank limit systems, furnace owner protection, and custom sounds.
Global refresh interval for the smelting and upgrade processing engine. Default is 1 tick for maximum precision and smoothness.
tick-rate: 1
Security rules for placed furnaces. Prohibits strangers from opening or breaking another player's furnace without permission or trusted access.
protection:
prevent-break: true
prevent-open: true
allow-hopper-access: false
Permission-based furnace placement limits. Players inherit the limits assigned to their rank group via ultrafurnaces.limit.<group>.
limits:
default:
total: 3
types:
basic: 3
advanced: 1
vip:
total: 10
types:
basic: 10
advanced: 5
Persistent storage backend for furnace blocks, upgrades, and inventories: SQLITE (local flatfile) or MYSQL (network database).
database:
type: SQLITE
Each furnace can equip 8 independent upgrade systems configurable via progression arrays.
Reduces cooking time in ticks per item (default Minecraft is 200 ticks = 10s).
speed:
1: 180
2: 140
3: 100
4: 60
5: 20
Fuel duration multiplier. Level 2 (2.0) means fuel burns twice as long.
efficiency:
1: 1.25
2: 1.50
3: 2.00
Vanilla XP orb drop multiplier when withdrawing items from the output slot.
experience:
1: 1.5
2: 2.0
3: 3.0
Vault currency generated directly into the owner's balance per smelted item.
money:
1: 0.5
2: 1.0
3: 2.5
Percentage chance to duplicate the resulting smelted item.
double:
1: 10.0
2: 25.0
3: 50.0
Expands internal virtual storage capacity inside the furnace management GUI.
storage:
1: 9
2: 18
3: 27
Percentage chance to discover random loot table items from treasures.yml during smelting.
treasures:
1: 2.5
2: 5.0
3: 10.0
Breakdown of each parameter present in furnace files under plugins/UltraFurnaces/furnaces/*.yml.
Physical block appearance and inventory item properties (material, display name, lore, glow, and custom-model-data).
display:
material: BLAST_FURNACE
name: "&6&lIndustrial Blast Furnace"
lore:
- "&7Smelts ores at blazing speeds."
glow: true
Floating text lines hovering above the placed furnace block with live placeholders.
hologram:
enabled: true
height: 1.2
lines:
- "&6&lIndustrial Furnace"
- "&7Owner: &f%owner%"
- "&7Speed: &a%speed% ticks"
List of active upgrades and max level caps allowed for this specific furnace tier.
enabled-upgrades:
- type: speed
max-level: 5
- type: efficiency
max-level: 3
- type: money
max-level: 3
Create unique smelting recipes stored in plugins/UltraFurnaces/recipes/*.yml.
Define required inputs and outputs with custom names, lore, and ItemsAdder identifiers.
input:
material: ROTTEN_FLESH
amount: 1
output:
material: LEATHER
amount: 1
chance: 100.0
Custom cook duration in ticks and base experience awarded upon collection.
cook-time: 100
experience: 2.5
Define specialized smelting fuels with custom burn durations and effects in fuels.yml.
Add custom fuel items by specifying their material, display name, lore, glow, and burn duration in ticks.
compressed_coal:
material: COAL
name: "&bCompressed Coal"
lore:
- "&7Burns 4x longer than regular coal."
glow: true
burn-time: 6400 # 320 seconds (32 items)
magic_fuel:
material: BLAZE_ROD
name: "&6Magic Blaze Rod"
burn-time: 12000 # 600 seconds (60 items)
Modular loot drop system that rewards lucky players with bonus items during smelting cycles.
Organize loot by weighted drop pools (common, rare, legendary) with nested item groups and custom item support.
common:
- material: COAL
amount: 5
chance: 50.0
- material: IRON_NUGGET
amount: 3
chance: 30.0
rare:
- material: DIAMOND
amount: 1
chance: 10.0
- material: EMERALD
amount: 2
chance: 15.0
Complete list of user and administrative commands for UltraFurnaces.
| Command & Syntax | Description | Permission |
|---|---|---|
| /uf give <player> <type> [amount] | Gives an upgraded furnace item to a player. | ultrafurnaces.command.give |
| /uf reload | Hot-reloads configuration files, recipes, fuels, and menus. | ultrafurnaces.command.reload |
| /uf item save <name> | Saves the currently held item into custom storage. | ultrafurnaces.command.item |
| /uf item delete <name> | Deletes a previously saved custom item. | ultrafurnaces.command.item |
| /uf trust <player> | Trusts a friend to open and access your targeted furnace. | ultrafurnaces.command.trust |
| /uf untrust <player> | Revokes a trusted player's access to your furnace. | ultrafurnaces.command.trust |
Internal descriptors for menus and PlaceholderAPI metrics for tabs and scoreboards.
| Placeholder | Description |
|---|---|
| %speed% | Current smelting speed value of the furnace in ticks. |
| %efficiency% | Current fuel burn efficiency multiplier. |
| %experience% | Current XP drop multiplier. |
| %money% | Vault currency generated per smelted item. |
| %extra_items% | Percentage chance to duplicate outputs. |
| %storage% | Current internal virtual storage capacity. |
| %treasures_chance% | Current treasure drop percentage chance. |
| Placeholder | Result |
|---|---|
| %ultrafurnaces_placed% | Total furnaces placed by the player. |
| %ultrafurnaces_placed_<type>% | Total furnaces of a specific tier placed by the player. |
| %ultrafurnaces_limit% | Global furnace placement limit of the player. |
| %ultrafurnaces_limit_<type>% | Placement limit for a specific furnace tier. |
UltraItemRoulette is a fast-paced round-based PvP minigame where players form a circle around a 3D roulette in the center. When the roulette stops, the selected player becomes the hunter with special equipment and must eliminate all others. Features automated arena rollback via FAWE, votable modes with custom kits, cosmetic win and elimination effects, SQL stats, and Vault economy support.
Authentic 3D deceleration curves, real-time spatial tick sounds, and vibrant glowing outlines for evaluated and selected candidates.
Create custom game modes with unique kits for the hunter and survivors, voting rules, and round timeouts.
High-speed zero-lag arena restoration powered by FAWE snapshots, automatic player respawn handling, and multi-arena queues.
Customizable victory dances, kill effects, death sounds, blood particles, SQL leaderboards, and Vault currency rewards.
Requirements and quick installation steps for UltraItemRoulette.
Place UltraItemRoulette.jar inside the plugins/ folder of your server.
FastAsyncWorldEdit (FAWE) or WorldEdit is recommended for instantaneous arena rollbacks between matches without lag.
Restart your server to automatically generate default game modes, 14 GUI interfaces, and cosmetic effects in plugins/UltraItemRoulette/.
Global game rules, PvP modes, round timers, roulette animation parameters, and economy rewards.
HUNT_SELECTED (others can only damage the chosen hunter) or FREE_FOR_ALL.
SELECTED_OUTCOME (ends when hunter dies or kills someone) or LAST_SURVIVOR.
allowed-commands.
ELIMINATE_SELECTED (eliminates hunter) or KEEP_SELECTED.
YELLOW) and final selection (RED).
INTERNAL, VAULT, EXCELLENT_ECONOMY, or CUSTOM.
VOTE, RANDOM, FIXED, or ADMIN_CHOICE.
Each mode file defines its vote priority, GUI icons, and kits assigned to the Selected Hunter (kits.selected) and Other Players (kits.others).
Game modes transform the combat dynamics of each round. During pre-match lobby, players vote for their preferred mode:
Players choose their favorite mode in the voting GUI. The mode with the most votes is selected for the match.
The server randomly picks an enabled mode among all YAML files in modes/.
Each file in modes/ can override global rules from config.yml:
rules.timeout.duration-seconds: Adjusts round timeout duration for this specific mode.rules.center-effect: Defines a unique center particle effect for this mode.schema-version: 1
enabled: true
display:
name: "<gradient:#FFAA00:#FFFF55>Default</gradient>"
icon: MACE
lore:
- "<gray>The default mode when no vote wins."
- "<gray>Selected kit: <white>Mace + 5 Wind Charges"
kits:
selected:
inventory:
0:
material: MACE
name: "<#FFAA00>Selected Player's Mace"
unbreakable: true
1:
material: WIND_CHARGE
amount: 5
selector-item:
material: MACE
glow: true
scale: 1.00
rules:
timeout:
duration-seconds: 30
schema-version: 1
enabled: true
display:
name: "<gradient:#FF5555:#FFAA00>Archer</gradient>"
icon: BOW
lore:
- "<gray>Bow battle with custom arrows."
kits:
selected:
inventory:
0:
material: BOW
name: "<#FF5555>Hunter's Recurve Bow"
unbreakable: true
1:
material: ARROW
amount: 16
Step-by-step administrator walkthrough to create, define spawn anchors, and save FAWE rollback-enabled arenas.
Run /uir create <name> to load the arena editor world. An isolated plot is generated automatically for building and defining boundaries.
Stand at the exact center of the arena and run /uir setcenteritem. Next, position yourself at each player spot and execute /uir addspawn until all player positions are configured.
Set the arena capacity with /uir setmaxplayers <count> and finalize by running /uir save. The arena snapshot will be compiled and ready to host games.
With /uir quickcreate <name> <floor_block> <max_players> [mode], you can generate complete working arenas with circular player distribution in seconds:
Standard circular layout with 7.0 blocks radius from the central item. Ideal for medium to large matches.
Reduced 4.5 block radius for smaller arenas and intense close-quarters combat.
The 14 default inventory GUIs generated by UltraItemRoulette, including main menu, arena browser, voting, cosmetics, and spectator tools.
title: "<#9d7171><bold>ItemRoulette</bold>"
rows: 3
items:
arenas:
slot: 11
material: COMPASS
name: "<green>Play Now"
cosmetics:
slot: 13
material: NETHER_STAR
name: "<yellow>Cosmetics"
stats:
slot: 15
material: BOOK
name: "<aqua>My Statistics"
title: "<#9d7171>Select Arena"
rows: 5
pagination:
enabled: true
slots: [10, 11, 12, 13, 14, 15, 16, 19, 20, 21, 22, 23, 24, 25]
title: "<#9d7171>Vote for Game Mode"
rows: 3
slots: [11, 12, 13, 14, 15]
title: "<#9d7171>Victory Celebrations"
rows: 4
Configuration of visual particle and audio effects for victory celebrations, player elimination bursts, and center roulette reveals.
Celebration sequences triggered around the winning survivor at match completion.
type: FIREWORK_SPIRAL
colors: ["#FFAA00", "#FF5555", "#55FFFF"]
duration-seconds: 5
type: LIGHTNING_STRIKE
sound: ENTITY_LIGHTNING_BOLT_THUNDER
safe-visual-only: true
Visual bursts and sound cues played at the exact coordinates where a player is eliminated.
particle: SOUL_FIRE_FLAME
count: 30
sound: ENTITY_BLAZE_DEATH
particle: EXPLOSION_NORMAL
count: 20
sound: ENTITY_GENERIC_EXPLODE
Complete reference of user and administrative commands for UltraItemRoulette.
| Command & Syntax | Description | Permission |
|---|---|---|
| /uir join [arena] | Joins a specific arena lobby or opens the arena selector. | ultraitemroulette.play |
| /uir leave | Leaves the current arena and restores previous inventory. | ultraitemroulette.play |
| /uir replay | Requests to requeue in the same arena. | ultraitemroulette.play |
| /uir vote <mode> | Votes for a game mode in the pre-match countdown. | ultraitemroulette.vote |
| /uir create <name> | Starts interactive arena creation session in editor world. | ultraitemroulette.admin |
| /uir quickcreate <name> <block> <max> | Instantly generates a preconfigured arena with circular spawns. | ultraitemroulette.admin |
| /uir fakeplayers <count> | Adds simulated bot players to test arena gameplay. | ultraitemroulette.admin |
| /uir start [arena] | Forces immediate start of a match in the arena. | ultraitemroulette.admin |
| /uir stop <arena> | Stops the active match and resets arena. | ultraitemroulette.admin |
| /uir delete <arena> | Permanently deletes an arena and its FAWE snapshot. | ultraitemroulette.admin |
| /uir reload | Reloads all configurations, modes, GUIs, and effects. | ultraitemroulette.admin |
Internal message variables and PlaceholderAPI (PAPI) metrics for scoreboards and holograms.
| Placeholder | Result |
|---|---|
| %player% / <player_name> | Current player name. |
| %selected% / <selected_player> | Name of hunter selected by the roulette. |
| %arena% / <arena> | Active arena identifier. |
| %mode% / <mode> | Public name of active game mode. |
| %round% / <round> | Current round number. |
| %time% / <time> | Remaining round time or countdown in seconds. |
| %alive% / <alive_players> | Number of surviving players in the round. |
| %score% / <score> | Player accumulated score/points. |
| %economy_balance% | Formatted economy balance (Vault/ExcellentEconomy). |
| Placeholder | Result |
|---|---|
| %ultraitemroulette_wins% | Total player wins. |
| %ultraitemroulette_kills% | Total player kills. |
| %ultraitemroulette_deaths% | Total player deaths. |
| %ultraitemroulette_games_played% | Total matches played. |
| %ultraitemroulette_arena_status_<id>% | Current status of specified arena (WAITING, STARTING, IN_GAME). |
| %ultraitemroulette_arena_players_<id>% | Current players in arena (e.g. 4/12). |
UltraCities is a block-based city and land protection system for Paper 1.21.11 and newer. Engineered with zero-lag asynchronous spatial chunk indexing, persistent 3D subzones, 65 typed protection flags, installable crystals, active shields, and global raid events.
Place a physical city core to claim territory. Each core type supports independent leveling, radius expansions, member capacity caps, and shared live chest storage.
Granular control over block physics, combat, explosions, vehicles, and environmental growth with distinct audience rules for owners, members, and visitors.
Socket modular crystals into city cores to provide potion buffs, AuraSkills XP multipliers, crop growth acceleration, temporary flight, or death interception.
Select 3D cuboids with particle wand wireframes. Subzone owners manage independent flags, add local members, and sell plots through an integrated real estate market.
Setting up UltraCities on your Minecraft server. Follow these steps for an optimal configuration.
Requires Java 21 or newer and Paper 1.21.11+ (or compatible forks like Purpur). Optional dependencies include Vault, ExcellentEconomy, and PlaceholderAPI.
Place the licensed marketplace UltraCities-1.0.1.jar into your server's plugins/ folder. Install only one UltraCities JAR at a time; readable and protected builds share the same plugin name and data.
Start your server. The licensed gameplay runtime initializes only after asynchronous license validation accepts the response or a verified SDK cache; configuration files, default core types and the SQLite database are then initialized. No main-thread network wait is used. License rejection disables the plugin. An unexpected initial validation exception leaves gameplay inactive and retries after 60 seconds; check the console before opening the server to players.
Run /uc give <player> basic to give yourself the starter city core block.
Place the core block on the ground and right-click it to open the interactive city control GUI.
plugins/UltraCities/
├── config.yml # Global settings, borders, wireframes, distance rules
├── messages.yml # Chat messages, actionbars, titles, flag denial texts
├── flags.yml # Global baseline defaults, entity lists, GUI displays
├── upgrade-effects.yml # Fireworks, sounds, and broadcast announcements
├── data/
│ └── ultracities.db # SQLite database (cities, subzones, members, skins)
├── license/ # Licensed edition only; never redistribute runtime identity/cache files
│ ├── license.yml
│ ├── license-cache.json
│ ├── .instalation
│ └── .license
├── city-blocks/ # Modular protection block types (e.g., basic.yml)
├── crystals/ # Installable modular crystal definitions
├── shields/ # Shield types, durations, and costs
├── events/ # Global event configurations (raids.yml, booster.yml)
└── guis/ # 6-row slot-controlled inventory menus
Release builds separate dist/obfuscated/ (licensed ProGuard artifact) from dist/unobfuscated/ (readable licensed diagnostic build and personal edition). The personal edition has no licensing and must stay private. Never distribute both editions together or publish private retracing maps. Back up server data before changing a plugin build.
The protected build renames UltraCities implementation classes without transforming native SQLite or the licensing SDK. Marketplace injection literals remain intact. Local operation gates use accepted in-memory authorization and do not make an HTTP request per click or command. Periodic validation follows the server's revalidarEn value with the existing one-hour minimum and twelve-hour fallback; signed offline-cache/grace handling remains owned by the SDK.
An experimental dist/obfuscated-aggressive/ profile is also built separately. It renames the descriptor entry point and internal authorization methods, strips source/line/local-variable metadata, and selectively optimizes authorization code. Gameplay, persistence, high-frequency listeners and optional integrations are excluded from optimization; external libraries remain unchanged. This profile does not add string encryption or commercial control-flow obfuscation. Private maps recover class/method names, not stripped source lines. Install only one JAR and validate this experimental profile on a backed-up staging server before production.
Both protected artifacts run offline lifecycle checks against transformed authorization classes: accepted/cached results, rejection, initial-error retry, heartbeat errors/rejection and shutdown. Only the mapped entry-point reference may change in plugin.yml; other configuration resources stay unchanged. Mocked checks do not validate actual server signatures or replace a test download after BuiltByBit personalization.
For private gameplay compatibility testing, dist/personal-obfuscated-aggressive/UltraCities-1.0.1-personal.jar uses the same aggressive ProGuard profile with no licensing code or SDK. It is built from the actual personal edition, not a modified marketplace artifact. Verification checks license isolation, class linkage, unchanged resources and sample gameplay behavior. This private build does not test license enforcement; never publish it or install it alongside another UltraCities JAR.
Obfuscation increases analysis effort but cannot make a downloadable plugin unmodifiable or AI-proof. Automated artifact checks preserve configuration/native resources and validate class linkage; test the protected build on a backed-up Paper staging server with your optional plugins before a public rollout. Build verification does not consume a real license or replace live server acceptance tests.
A concise reference to the bundled city-blocks/basic.yml: the core item, block-specific rules and city levels.
This page describes only city-blocks/basic.yml, the protection block included with UltraCities. The examples below are excerpts from that file: edit the existing sections rather than replacing the whole file with an excerpt.
The id identifies the protection type in items and saved cities. Keep it unchanged once the type is in use; the filename is only organizational. A second protection type needs a different ID.
id: basic
enabled: true
material: BEACON
name: "&6City Core"
lore:
- "&7Place it to protect your base."
- "&7Type: &ebasic"
- "&7Stored level: &e{saved-level}"
home:
enabled: true
auto-set-on-place: true
allow-members: true
worlds:
mode: BLACKLIST
list:
- world_nether
- world_the_end
worldguard:
prevent-region-overlap: true
material, name and lore define the core players receive. The material must be a real block.home.enabled enables normal home travel; auto-set-on-place saves a home above new cores; allow-members includes full members as well as owners.worlds.mode accepts BLACKLIST (deny listed worlds) or WHITELIST (allow only listed worlds).worldguard.prevent-region-overlap rejects initial placement inside named WorldGuard regions when that plugin is present.These sections are at the file's top level, not inside levels.
| Section | What it controls |
|---|---|
command-restrictions |
enabled, BLACKLIST/WHITELIST mode, command list, and exempt access: OWNERS or MEMBERS. |
allowed-shields |
Shield IDs available to this type; the bundled block allows wooden and royal. |
subzones |
Enable subzones and allow or prevent overlap between them. Their capacities are set per level. |
particles |
Ambient core particles: type, delay-ticks, count, radius, offsets, extra and visibility-radius. |
hologram |
Floating text: enabled, height above the core and configurable lines. |
messages.enter / messages.exit |
Border messages in chat, title, subtitle, actionbar or bossbar.message. Empty channels are disabled. |
flags.editable |
Flags owners may change, with permitted states and audiences for each one. |
flags.defaults |
Optional local flag defaults; absent from the bundled file. Local overrides take precedence over inherited defaults. |
flags.options |
Values for weather-clock and time-lock when those rules are used. |
For example, the bundled build flag allows ALLOW/DENY with audiences NON_MEMBERS or ALL. pvp has the same choices. ALL applies to owners too; restricting the audience list prevents owners from selecting other audiences.
The bundled basic.yml contains seven levels. Each numeric entry under levels defines that level's benefits. Keep consecutive keys starting at 1; write every level's values explicitly rather than expecting inheritance.
| Field | Bundled level 1 → level 2 |
|---|---|
radius |
12 → 20: square radius from the core, over the world's full build height. Radius 12 covers 25 × 25 blocks. |
max-members |
3 → 7: member capacity, excluding owners. |
chest-rows |
1 → 3: storage rows, from 1 to 6. |
crystal-slots |
1 → 3: installed-crystal capacity. |
raid-block-hits |
3 → 5: base block resistance during permitted raids. |
max-subzones |
1 → 2: maximum subzone count. |
max-subzone-blocks |
256 → 1000: maximum inclusive volume of each subzone. |
change-name |
true: allow city renaming at that level. |
allowed-crystal-rarities |
Optional rarity whitelist, commented out by default. Omitted or empty allows every rarity. |
The remaining sections also belong inside each destination level:
| Section | How to use it |
|---|---|
gui-display |
Level item material, name, lore and glow. Write benefit and requirement descriptions here; lore alone does not enforce them. |
upgrade-cost |
Enable payment and choose ALL/ANY across Vault, ExcellentEconomy and item groups. Level 2's bundled example requires 1,000 Vault coins, 1,000 ExcellentEconomy coins, 5 gems, 2 tokens, 32 gold ingots and 4 diamonds. Disable unused groups. |
required-permissions |
ALL/ANY mode and a permissions list. Empty by default; add the permission nodes the purchaser must have. |
conditions |
ALL/ANY mode and an expressions list, for example %player_level% >= 10. Empty by default; placeholders need their relevant expansions. |
commands |
Commands executed after reaching this level, with [CONSOLE], [PLAYER] or [OP]. Empty by default. |
For level-item lore, {current-radius} / {target-radius} and the equivalent members, storage, crystals and raid-hit variables show the previous configured value and the destination value. Keep the lore consistent with the actual settings.
Expand the exact default file below to inspect its sections and all seven levels. This is the plugin's bundled example, not your server's customized file. Keep IDs and existing level keys stable; after editing your own file, use /city reload and check configuration warnings.
# Persistent identifier used by items, commands and saved cities. The file name is only organizational.
# Whitespace is normalized to hyphens; every city-block file must ultimately have a unique ID.
id: basic
# Shared homes for cities created with this block type.
home:
# Disables /city home, /city sethome and normal GUI home travel for this type.
# Saved homes are retained; operator-only administrative teleports remain available.
enabled: true
# Saves the initial home centered one block above the core when a NEW city is placed.
# Disabling this requires an owner to use /city sethome; existing homes are not changed.
auto-set-on-place: true
# Allows full members to use /city home and GUI home travel. Owners always retain access.
# Players with individual flags alone do not qualify. home.enabled must also be true.
allow-members: true
# Enables this city block type and defines the item players receive.
enabled: true
material: BEACON
name: "&6City Core"
lore:
- "&7Place it to protect your base."
- "&7Type: &ebasic"
- "&7Stored level: &e{saved-level}"
# Controls which worlds accept this protection block.
# WHITELIST permits only listed worlds; BLACKLIST permits every world except those listed.
worlds:
mode: BLACKLIST
list:
- world_nether
- world_the_end
# When WorldGuard is installed, the complete initial city area cannot intersect one of its named regions.
# The special __global__ region is ignored. Disable this option for this block type if overlap is intentional.
worldguard:
prevent-region-overlap: true
# Restricts commands used by non-members while they are physically inside this city type.
# BLACKLIST blocks only listed commands. WHITELIST blocks every command except those listed.
# Entries may include the leading slash and may target either a root command or a specific subcommand.
# access: OWNERS exempts only the city owner; MEMBERS exempts the owner and full members.
# Players with individual flags are not full members. ultracities.bypass always bypasses restrictions.
command-restrictions:
enabled: true
mode: BLACKLIST
access: MEMBERS
# OWNERS: only the owner can bypass command restrictions.
# MEMBERS: the owner and full members can bypass command restrictions.
list: []
# Examples:
# - "/sethome"
# - "/sell all"
allowed-shields: [wooden, royal]
# Subzones are selected as 3D cuboids inside this city type.
subzones:
enabled: true
# When false, a new subzone cannot intersect an existing one in the same city.
allow-overlap: false
particles:
enabled: true
type: END_ROD
delay-ticks: 20
count: 3
radius: 0.65
offset-x: 0.0
offset-y: 0.8
offset-z: 0.0
extra: 0.0
visibility-radius: 48.0
# Floating text displayed above every loaded core of this block type.
# Available placeholders include {city}, {tag}, {owner-name}, {level}, {max-level}, {radius},
# {members}, {max-members}, {storage-rows}, {crystal-slots}, {raid-hits}, {world}, {x}, {y} and {z}.
# Prefix any line with [LEFT], [CENTER] or [RIGHT] to choose its independent text alignment.
# Lines without an alignment prefix use [CENTER]. The prefix itself is never displayed.
# With no leading spaces, LEFT and RIGHT use the lateral distance configured in config.yml.
# Spaces before [LEFT] move its starting edge towards the center; spaces before [RIGHT] do the opposite.
# These offsets are invisible and never enlarge the background.
# Spaces after the marker are rendered normally and therefore do affect the background.
# Example: " [LEFT]&fText" moves seven steps right from the default left anchor and grows rightward.
hologram:
enabled: true
# Vertical offset measured from the protection block's Y coordinate.
height: 3.25
lines:
- "&6&l{city}"
- ""
- " [LEFT] &8| &r&7Level: &e{level}&7/&e{max-level}"
- " [LEFT] &8| &r&7Radius: &f{radius}"
- " [LEFT] &8| &7Members: &f{members}&7/&f{max-members}"
- ""
- "&eRight-click to open the menu."
# Messages displayed after a successful city-border transition.
# Chat accepts either one line or a list. Empty title, subtitle and bossbar messages disable those channels.
messages:
enter:
chat:
- "&aYou entered the city &f{city}&a."
title: ""
subtitle: ""
actionbar: "&a&l✔ &r&aEntering &f{city}"
bossbar:
message: ""
color: GREEN
overlay: PROGRESS
duration-seconds: 3.0
exit:
chat:
- "&cYou left the city &f{city}&c."
title: ""
subtitle: ""
actionbar: "&c&l✘ &r&cLeaving &f{city}"
bossbar:
message: ""
color: RED
overlay: PROGRESS
duration-seconds: 3.0
# Defaults are inherited from flags.yml. This block intentionally has no local default overrides.
flags:
options:
weather-clock: CLEAR
time-lock: 6000
# Only these flags are visible and editable in this block type's flags menu.
# states and audiences also limit the values owners may select with left and right click.
editable:
build:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL]
interact:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
block-break:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
block-place:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
use:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
fishing-rod:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
wind-charge:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
potion-splash:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
damage-animals:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
damage-mobs:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
damage-villagers:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
chest-access:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
villager-trading:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
tnt:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL]
pvp:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL]
use-anvil:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
use-portals:
states: [ALLOW, DENY]
audiences: [NON_MEMBERS, ALL, MEMBERS]
levels:
1:
radius: 12
max-members: 3
chest-rows: 1
crystal-slots: 1
# Optional rarity whitelist. Omit or use [] to allow every crystal rarity.
# Crystals without a rarity do not match a non-empty whitelist.
# allowed-crystal-rarities: [COMMON]
raid-block-hits: 3
max-subzones: 1
max-subzone-blocks: 256
change-name: true
# Commands executed in order when an upgrade reaches this level (not on placement/reload).
# Supported senders: [CONSOLE], [PLAYER], [OP]. OP is temporary; use trusted commands only.
# Available variables include {player}, {city}, {level}, and {previous-level}.
# Example:
# commands:
# - "[CONSOLE] give {player} diamond 1"
# - "[PLAYER] say My city has reached level {level}!"
# - "[OP] say Upgrade completed!"
commands: []
# Optional destination-level permissions. ALL requires every node; ANY requires one.
# Checked on the upgrading player before charging; an empty list adds no restriction.
required-permissions:
mode: ALL
permissions: []
# Example: ["ultracities.upgrade.level.2", "server.rank.vip"]
# Optional comparisons using PlaceholderAPI values. Both requirement sections must pass.
# Operators: ==, !=, >=, <=, >, <. Ordering is numeric; text equality ignores case.
# Use decimal points, not comma separators. No scripts or chained expressions.
# Missing PlaceholderAPI/expansions, unresolved placeholders or invalid values block upgrades.
# ALL requires every comparison; ANY requires one (invalid comparisons always block).
conditions:
mode: ALL
expressions: []
# Example:
# expressions:
# - "%ultracities_city_amount_level_1% >= 1"
# - "%ultracities_city_level_2% == yes"
gui-display:
material: STONE
# Used only when material is PLAYER_HEAD: Base64 texture or direct skin URL.
# value: ""
name: "&7City Level &f1"
lore:
- " &8| &7Radius: &f12"
- " &8| &7Members: &f3"
- " &8| &7Storage rows: &f1"
- " &8| &7Crystal slots: &f1"
- " &8| &7Raid hits: &f3"
- " &8| &7Subzones: &f1"
- " &8| &7Max subzone blocks: &f256"
glow: false
upgrade-cost:
enabled: false
mode: ALL
vault:
enabled: false
amount: 0.0
display-name: "&6Coins"
excellent-economy:
enabled: false
currencies: []
items:
enabled: false
requirements: []
2:
radius: 20
max-members: 7
chest-rows: 3
crystal-slots: 3
# Optional rarity whitelist; omit or use [] for no restriction.
# allowed-crystal-rarities: [COMMON]
raid-block-hits: 5
max-subzones: 2
max-subzone-blocks: 1000
change-name: true
# Commands executed in order when an upgrade reaches this level (not on placement/reload).
# Supported senders: [CONSOLE], [PLAYER], [OP]. OP is temporary; use trusted commands only.
# Available variables include {player}, {city}, {level}, and {previous-level}.
# Example:
# commands:
# - "[CONSOLE] give {player} diamond 1"
# - "[PLAYER] say My city has reached level {level}!"
# - "[OP] say Upgrade completed!"
commands: []
# Optional destination-level permissions. ALL requires every node; ANY requires one.
# Checked on the upgrading player before charging; an empty list adds no restriction.
required-permissions:
mode: ALL
permissions: []
# Example: ["ultracities.upgrade.level.2", "server.rank.vip"]
# Optional comparisons using PlaceholderAPI values. Both requirement sections must pass.
# Operators: ==, !=, >=, <=, >, <. Ordering is numeric; text equality ignores case.
# Use decimal points, not comma separators. No scripts or chained expressions.
# Missing PlaceholderAPI/expansions, unresolved placeholders or invalid values block upgrades.
# ALL requires every comparison; ANY requires one (invalid comparisons always block).
conditions:
mode: ALL
expressions: []
# Example:
# expressions:
# - "%ultracities_city_amount_level_1% >= 1"
# - "%ultracities_city_level_2% == yes"
gui-display:
material: GOLD_INGOT
# Used only when material is PLAYER_HEAD: Base64 texture or direct skin URL.
# value: ""
name: "City Level &f2"
lore:
- " &8| &7Radius: &f{current-radius} &7➟ &a{target-radius}"
- " &8| &7Members: &f{current-members} &7➟ &a{target-members}"
- " &8| &7Storage rows: &f{current-storage-rows} &7➟ &a{target-storage-rows}"
- " &8| &7Crystal slots: &f{current-crystal-slots} &7➟ &a{target-crystal-slots}"
- " &8| &7Raid hits: &f{current-raid-hits} &7➟ &a{target-raid-hits}"
- " &8| &7Subzones: &f{current-subzones} &7➟ &a{target-subzones}"
- " &8| &7Max subzone blocks: &f{current-subzone-blocks} &7➟ &a{target-subzone-blocks}"
- ""
- "&eRequirements &7(all enabled methods):"
- " &8| &7Vault: &f{vault-amount} {vault-name}"
- " &8| &7ExcellentEconomy: &f{currency-coins-amount} {currency-coins-name}&7, &f{currency-gems-amount} {currency-gems-name} &7and &f{currency-tokens-amount} {currency-tokens-name}"
- " &8| &7Items: &f32 Gold Ingots and 4 Diamonds"
glow: true
upgrade-cost:
enabled: true
mode: ALL
vault:
enabled: true
amount: 1000.0
display-name: "&6Coins"
excellent-economy:
enabled: true
currencies:
- id: coins
amount: 1000.0
display-name: "&eCoins"
- id: gems
amount: 5.0
display-name: "&bGems"
- id: tokens
amount: 2.0
display-name: "&dTokens"
items:
enabled: true
requirements:
- material: GOLD_INGOT
amount: 32
- material: DIAMOND
amount: 4
3:
radius: 32
max-members: 15
chest-rows: 6
crystal-slots: 5
# Optional rarity whitelist; omit or use [] for no restriction.
# allowed-crystal-rarities: [COMMON]
raid-block-hits: 8
max-subzones: 3
max-subzone-blocks: 4096
change-name: true
# Commands executed in order when an upgrade reaches this level (not on placement/reload).
# Supported senders: [CONSOLE], [PLAYER], [OP]. OP is temporary; use trusted commands only.
# Available variables include {player}, {city}, {level}, and {previous-level}.
# Example:
# commands:
# - "[CONSOLE] give {player} diamond 1"
# - "[PLAYER] say My city has reached level {level}!"
# - "[OP] say Upgrade completed!"
commands: []
# Optional destination-level permissions. ALL requires every node; ANY requires one.
# Checked on the upgrading player before charging; an empty list adds no restriction.
required-permissions:
mode: ALL
permissions: []
# Example: ["ultracities.upgrade.level.2", "server.rank.vip"]
# Optional comparisons using PlaceholderAPI values. Both requirement sections must pass.
# Operators: ==, !=, >=, <=, >, <. Ordering is numeric; text equality ignores case.
# Use decimal points, not comma separators. No scripts or chained expressions.
# Missing PlaceholderAPI/expansions, unresolved placeholders or invalid values block upgrades.
# ALL requires every comparison; ANY requires one (invalid comparisons always block).
conditions:
mode: ALL
expressions: []
# Example:
# expressions:
# - "%ultracities_city_amount_level_1% >= 1"
# - "%ultracities_city_level_2% == yes"
gui-display:
material: DIAMOND
# Used only when material is PLAYER_HEAD: Base64 texture or direct skin URL.
# value: ""
name: "City Level &f3"
lore:
- " &8| &7Radius: &f{current-radius} &7➟ &a{target-radius}"
- " &8| &7Members: &f{current-members} &7➟ &a{target-members}"
- " &8| &7Storage rows: &f{current-storage-rows} &7➟ &a{target-storage-rows}"
- " &8| &7Crystal slots: &f{current-crystal-slots} &7➟ &a{target-crystal-slots}"
- " &8| &7Raid hits: &f{current-raid-hits} &7➟ &a{target-raid-hits}"
- " &8| &7Subzones: &f{current-subzones} &7➟ &a{target-subzones}"
- " &8| &7Max subzone blocks: &f{current-subzone-blocks} &7➟ &a{target-subzone-blocks}"
- ""
- "&eRequirements &7(all enabled methods):"
- " &8| &7Vault: &f{vault-amount} {vault-name}"
- " &8| &7ExcellentEconomy: &f{currency-coins-amount} {currency-coins-name} &7and &f{currency-gems-amount} {currency-gems-name}"
- " &8| &7Items: &f16 Gold Blocks and 12 Diamonds"
glow: true
upgrade-cost:
enabled: true
mode: ALL
vault:
enabled: true
amount: 2500.0
display-name: "&6Coins"
excellent-economy:
enabled: true
currencies:
- id: coins
amount: 2500.0
display-name: "&eCoins"
- id: gems
amount: 12.0
display-name: "&bGems"
items:
enabled: true
requirements:
- material: GOLD_BLOCK
amount: 16
- material: DIAMOND
amount: 12
4:
radius: 44
max-members: 22
chest-rows: 6
crystal-slots: 6
# Optional rarity whitelist; add COMMON too if both rarities should be allowed.
# allowed-crystal-rarities: [RARE]
raid-block-hits: 11
max-subzones: 4
max-subzone-blocks: 8192
change-name: true
# Commands executed in order when an upgrade reaches this level (not on placement/reload).
# Supported senders: [CONSOLE], [PLAYER], [OP]. OP is temporary; use trusted commands only.
# Available variables include {player}, {city}, {level}, and {previous-level}.
# Example:
# commands:
# - "[CONSOLE] give {player} diamond 1"
# - "[PLAYER] say My city has reached level {level}!"
# - "[OP] say Upgrade completed!"
commands: []
# Optional destination-level permissions. ALL requires every node; ANY requires one.
# Checked on the upgrading player before charging; an empty list adds no restriction.
required-permissions:
mode: ALL
permissions: []
# Example: ["ultracities.upgrade.level.2", "server.rank.vip"]
# Optional comparisons using PlaceholderAPI values. Both requirement sections must pass.
# Operators: ==, !=, >=, <=, >, <. Ordering is numeric; text equality ignores case.
# Use decimal points, not comma separators. No scripts or chained expressions.
# Missing PlaceholderAPI/expansions, unresolved placeholders or invalid values block upgrades.
# ALL requires every comparison; ANY requires one (invalid comparisons always block).
conditions:
mode: ALL
expressions: []
# Example:
# expressions:
# - "%ultracities_city_amount_level_1% >= 1"
# - "%ultracities_city_level_2% == yes"
gui-display:
material: EMERALD
name: "City Level &f4"
lore:
- " &8| &7Radius: &f{current-radius} &7➟ &a{target-radius}"
- " &8| &7Members: &f{current-members} &7➟ &a{target-members}"
- " &8| &7Storage rows: &f{current-storage-rows} &7➟ &a{target-storage-rows}"
- " &8| &7Crystal slots: &f{current-crystal-slots} &7➟ &a{target-crystal-slots}"
- " &8| &7Raid hits: &f{current-raid-hits} &7➟ &a{target-raid-hits}"
- " &8| &7Subzones: &f{current-subzones} &7➟ &a{target-subzones}"
- " &8| &7Max subzone blocks: &f{current-subzone-blocks} &7➟ &a{target-subzone-blocks}"
- ""
- "&eRequirements &7(all enabled methods):"
- " &8| &7Vault: &f{vault-amount} {vault-name}"
- " &8| &7Items: &f24 Emeralds and 16 Diamonds"
glow: true
upgrade-cost:
enabled: true
mode: ALL
vault:
enabled: true
amount: 5000.0
display-name: "&6Coins"
excellent-economy:
enabled: false
currencies: []
items:
enabled: true
requirements:
- material: EMERALD
amount: 24
- material: DIAMOND
amount: 16
5:
radius: 56
max-members: 30
chest-rows: 6
crystal-slots: 7
# Optional rarity whitelist; omit or use [] for no restriction.
# allowed-crystal-rarities: [RARE]
raid-block-hits: 14
max-subzones: 5
max-subzone-blocks: 16384
change-name: true
# Commands executed in order when an upgrade reaches this level (not on placement/reload).
# Supported senders: [CONSOLE], [PLAYER], [OP]. OP is temporary; use trusted commands only.
# Available variables include {player}, {city}, {level}, and {previous-level}.
# Example:
# commands:
# - "[CONSOLE] give {player} diamond 1"
# - "[PLAYER] say My city has reached level {level}!"
# - "[OP] say Upgrade completed!"
commands: []
# Optional destination-level permissions. ALL requires every node; ANY requires one.
# Checked on the upgrading player before charging; an empty list adds no restriction.
required-permissions:
mode: ALL
permissions: []
# Example: ["ultracities.upgrade.level.2", "server.rank.vip"]
# Optional comparisons using PlaceholderAPI values. Both requirement sections must pass.
# Operators: ==, !=, >=, <=, >, <. Ordering is numeric; text equality ignores case.
# Use decimal points, not comma separators. No scripts or chained expressions.
# Missing PlaceholderAPI/expansions, unresolved placeholders or invalid values block upgrades.
# ALL requires every comparison; ANY requires one (invalid comparisons always block).
conditions:
mode: ALL
expressions: []
# Example:
# expressions:
# - "%ultracities_city_amount_level_1% >= 1"
# - "%ultracities_city_level_2% == yes"
gui-display:
material: NETHERITE_INGOT
name: "City Level &f5"
lore:
- " &8| &7Radius: &f{current-radius} &7➟ &a{target-radius}"
- " &8| &7Members: &f{current-members} &7➟ &a{target-members}"
- " &8| &7Storage rows: &f{current-storage-rows} &7➟ &a{target-storage-rows}"
- " &8| &7Crystal slots: &f{current-crystal-slots} &7➟ &a{target-crystal-slots}"
- " &8| &7Raid hits: &f{current-raid-hits} &7➟ &a{target-raid-hits}"
- " &8| &7Subzones: &f{current-subzones} &7➟ &a{target-subzones}"
- " &8| &7Max subzone blocks: &f{current-subzone-blocks} &7➟ &a{target-subzone-blocks}"
- ""
- "&eRequirements &7(all enabled methods):"
- " &8| &7Vault: &f{vault-amount} {vault-name}"
- " &8| &7Items: &f4 Netherite Ingots and 24 Diamonds"
glow: true
upgrade-cost:
enabled: true
mode: ALL
vault:
enabled: true
amount: 10000.0
display-name: "&6Coins"
excellent-economy:
enabled: false
currencies: []
items:
enabled: true
requirements:
- material: NETHERITE_INGOT
amount: 4
- material: DIAMOND
amount: 24
6:
radius: 72
max-members: 40
chest-rows: 6
crystal-slots: 8
# Optional rarity whitelist; omit or use [] for no restriction.
# allowed-crystal-rarities: [RARE]
raid-block-hits: 18
max-subzones: 7
max-subzone-blocks: 32768
change-name: true
# Commands executed in order when an upgrade reaches this level (not on placement/reload).
# Supported senders: [CONSOLE], [PLAYER], [OP]. OP is temporary; use trusted commands only.
# Available variables include {player}, {city}, {level}, and {previous-level}.
# Example:
# commands:
# - "[CONSOLE] give {player} diamond 1"
# - "[PLAYER] say My city has reached level {level}!"
# - "[OP] say Upgrade completed!"
commands: []
# Optional destination-level permissions. ALL requires every node; ANY requires one.
# Checked on the upgrading player before charging; an empty list adds no restriction.
required-permissions:
mode: ALL
permissions: []
# Example: ["ultracities.upgrade.level.2", "server.rank.vip"]
# Optional comparisons using PlaceholderAPI values. Both requirement sections must pass.
# Operators: ==, !=, >=, <=, >, <. Ordering is numeric; text equality ignores case.
# Use decimal points, not comma separators. No scripts or chained expressions.
# Missing PlaceholderAPI/expansions, unresolved placeholders or invalid values block upgrades.
# ALL requires every comparison; ANY requires one (invalid comparisons always block).
conditions:
mode: ALL
expressions: []
# Example:
# expressions:
# - "%ultracities_city_amount_level_1% >= 1"
# - "%ultracities_city_level_2% == yes"
gui-display:
material: NETHER_STAR
name: "City Level &f6"
lore:
- " &8| &7Radius: &f{current-radius} &7➟ &a{target-radius}"
- " &8| &7Members: &f{current-members} &7➟ &a{target-members}"
- " &8| &7Storage rows: &f{current-storage-rows} &7➟ &a{target-storage-rows}"
- " &8| &7Crystal slots: &f{current-crystal-slots} &7➟ &a{target-crystal-slots}"
- " &8| &7Raid hits: &f{current-raid-hits} &7➟ &a{target-raid-hits}"
- " &8| &7Subzones: &f{current-subzones} &7➟ &a{target-subzones}"
- " &8| &7Max subzone blocks: &f{current-subzone-blocks} &7➟ &a{target-subzone-blocks}"
- ""
- "&eRequirements &7(all enabled methods):"
- " &8| &7Vault: &f{vault-amount} {vault-name}"
- " &8| &7Items: &f1 Nether Star and 8 Netherite Ingots"
glow: true
upgrade-cost:
enabled: true
mode: ALL
vault:
enabled: true
amount: 20000.0
display-name: "&6Coins"
excellent-economy:
enabled: false
currencies: []
items:
enabled: true
requirements:
- material: NETHER_STAR
amount: 1
- material: NETHERITE_INGOT
amount: 8
7:
radius: 88
max-members: 50
chest-rows: 6
crystal-slots: 10
# Optional rarity whitelist; omit or use [] for no restriction.
# allowed-crystal-rarities: [RARE]
raid-block-hits: 22
max-subzones: 10
max-subzone-blocks: 65536
change-name: true
# Commands executed in order when an upgrade reaches this level (not on placement/reload).
# Supported senders: [CONSOLE], [PLAYER], [OP]. OP is temporary; use trusted commands only.
# Available variables include {player}, {city}, {level}, and {previous-level}.
# Example:
# commands:
# - "[CONSOLE] give {player} diamond 1"
# - "[PLAYER] say My city has reached level {level}!"
# - "[OP] say Upgrade completed!"
commands: []
# Optional destination-level permissions. ALL requires every node; ANY requires one.
# Checked on the upgrading player before charging; an empty list adds no restriction.
required-permissions:
mode: ALL
permissions: []
# Example: ["ultracities.upgrade.level.2", "server.rank.vip"]
# Optional comparisons using PlaceholderAPI values. Both requirement sections must pass.
# Operators: ==, !=, >=, <=, >, <. Ordering is numeric; text equality ignores case.
# Use decimal points, not comma separators. No scripts or chained expressions.
# Missing PlaceholderAPI/expansions, unresolved placeholders or invalid values block upgrades.
# ALL requires every comparison; ANY requires one (invalid comparisons always block).
conditions:
mode: ALL
expressions: []
# Example:
# expressions:
# - "%ultracities_city_amount_level_1% >= 1"
# - "%ultracities_city_level_2% == yes"
gui-display:
material: BEACON
name: "City Level &f7"
lore:
- " &8| &7Radius: &f{current-radius} &7➟ &a{target-radius}"
- " &8| &7Members: &f{current-members} &7➟ &a{target-members}"
- " &8| &7Storage rows: &f{current-storage-rows} &7➟ &a{target-storage-rows}"
- " &8| &7Crystal slots: &f{current-crystal-slots} &7➟ &a{target-crystal-slots}"
- " &8| &7Raid hits: &f{current-raid-hits} &7➟ &a{target-raid-hits}"
- " &8| &7Subzones: &f{current-subzones} &7➟ &a{target-subzones}"
- " &8| &7Max subzone blocks: &f{current-subzone-blocks} &7➟ &a{target-subzone-blocks}"
- ""
- "&eRequirements &7(all enabled methods):"
- " &8| &7Vault: &f{vault-amount} {vault-name}"
- " &8| &7Items: &f1 Beacon and 16 Netherite Ingots"
glow: true
upgrade-cost:
enabled: true
mode: ALL
vault:
enabled: true
amount: 40000.0
display-name: "&6Coins"
excellent-economy:
enabled: false
currencies: []
items:
enabled: true
requirements:
- material: BEACON
amount: 1
- material: NETHERITE_INGOT
amount: 16
UltraCities provides 65 typed protection flags with full control over blocks, combat, physics, vehicles, and the environment. Each flag can be configured with discrete boolean states and target audiences.
Flags follow a three-tier cascade: 1. Global Defaults (defined in flags.yml) provide baseline settings; 2. Block Defaults (in city-blocks/*.yml) override globals for specific core tiers; and 3. In-Game GUI allows city owners to toggle editable rules in real time.
Inside the flag GUI, Left-Click toggles the rule state (ALLOW / DENY) and Right-Click cycles through permitted audiences: ALL, MEMBERS, NON_MEMBERS, OWNERS, and NON_OWNERS.
| Flag | Type | Description |
|---|---|---|
| build | ALLOW/DENY | Master building permission governing general block breaking, placing, and structural modifications. |
| block-break | ALLOW/DENY | Allows or prevents destroying blocks independently from the master build permission. |
| block-place | ALLOW/DENY | Allows or prevents placing blocks independently from the master build permission. |
| block-trampling | ALLOW/DENY | Prevents farmland from reverting to dirt and turtle eggs from cracking when jumped on. |
| pistons | ALLOW/DENY | Controls piston pushes and retractions that occur entirely within city borders. |
| pistons-out | ALLOW/DENY | Governs pistons pushing blocks across borders into or pulling blocks out of the city. |
| interact | ALLOW/DENY | Controls physical interaction with armor stands, item frames, and miscellaneous entities. |
| use | ALLOW/DENY | Governs opening doors, trapdoors, fence gates, levers, stonecutters, and workstation blocks. |
| chest-access | ALLOW/DENY | Controls opening and withdrawing items from chests, trapped chests, barrels, and shulker boxes. |
| use-anvil | ALLOW/DENY | Controls opening and using repair, rename, and combine interfaces in anvils. |
| use-portals | ALLOW/DENY | Governs entering and teleporting through Nether portals and End portal frames. |
| item-frame-rotation | ALLOW/DENY | Controls rotating items mounted inside regular and glow item frames. |
| villager-trading | ALLOW/DENY | Controls opening the trading window and trading emeralds with villagers and wandering traders. |
| fishing-rod | ALLOW/DENY | Controls casting fishing rods and hooking entities or blocks inside the city. |
| pvp | ALLOW/DENY | Controls player-versus-player melee combat, projectile damage, and sweeps within city borders. |
| damage-animals | ENTITY_SET | Governs attacking peaceful and passive animals. Supports Bukkit EntityType filter lists. |
| damage-mobs | ENTITY_SET | Governs attacking hostile and neutral monster mobs. Supports Bukkit EntityType filter lists. |
| damage-villagers | ALLOW/DENY | Protects villagers and wandering traders from being damaged or slain by players. |
| mob-damage | ALLOW/DENY | Controls whether hostile monsters can deal damage to players inside the city. |
| fall-damage | ALLOW/DENY | Controls taking fall damage upon landing from high heights within city territory. |
| firework-damage | ALLOW/DENY | Controls damage to players and entities caused by exploding firework rockets and crossbows. |
| potion-splash | ALLOW/DENY | Controls splash and lingering potion projectile impacts and area-of-effect clouds. |
| wind-charge | ALLOW/DENY | Governs firing and impact knockback physics of breeze wind charges. |
| tnt | ALLOW/DENY | Controls TNT block placement, priming, and explosion damage to structures. |
| creeper-explosion | ALLOW/DENY | Governs block destruction and entity damage caused by creeper detonations. |
| ghast-fireball | ALLOW/DENY | Governs explosion damage and fiery crater creation from ghast fireballs. |
| enderdragon-block-damage | ALLOW/DENY | Prevents the Ender Dragon's flight and body collision from breaking blocks. |
| wither-damage | ALLOW/DENY | Controls block shattering, wither skulls, and spawning blast damage from the Wither. |
| other-explosion | ALLOW/DENY | Controls miscellaneous explosions such as respawn anchors, end crystals, and bed explosions. |
| enderman-grief | ALLOW/DENY | Prevents Endermen from picking up, carrying, or placing blocks in the city. |
| ravager-grief | ALLOW/DENY | Prevents ravager roars, charging, and walking from destroying crops and foliage. |
| lighter | ALLOW/DENY | Controls striking flint and steel or using fire charges to ignite blocks. |
| entry | ALLOW/DENY | Governs entering across the city boundary. Denied players are repelled with knockback. |
| exit | ALLOW/DENY | Governs leaving the city boundary. Denied players are pushed back toward the interior. |
| enderpearl | ALLOW/DENY | Controls throwing and teleporting via ender pearls into or out of the city. |
| chorus-fruit-teleport | ALLOW/DENY | Controls random spatial teleportation triggered when eating chorus fruit. |
| fly | ALLOW/DENY | Allows or revokes flight mode for players within the city cuboid. |
| ride | ALLOW/DENY | Governs mounting and riding horses, donkeys, camels, striders, and rideable animals. |
| sleep | ALLOW/DENY | Controls entering and sleeping in beds within the city to pass the night. |
| vehicle-place | ALLOW/DENY | Governs placing boats, chest boats, minecarts, and other vehicle entities. |
| vehicle-destroy | ALLOW/DENY | Governs breaking or dealing damage to boats, minecarts, and vehicles. |
| vehicle-use | ALLOW/DENY | Controls entering and piloting vehicle entities (boats, minecarts) inside city borders. |
| mob-spawning | ENTITY_SET | Controls natural mob spawning. Supports Bukkit EntityType filter lists. |
| deny-spawn | ENTITY_SET | Denies specific entity types from spawning within city territory. |
| water-flow | ALLOW/DENY | Governs water spreading, liquid stream physics, and infinite water generation. |
| lava-flow | ALLOW/DENY | Governs lava spreading, fluid flow physics, and cobblestone generation. |
| lava-fire | ALLOW/DENY | Governs lava igniting nearby flammable blocks (wood, wool, leaves). |
| fire-spread | ALLOW/DENY | Governs natural propagation of fire between combustible adjacent blocks. |
| lightning | ALLOW/DENY | Controls natural lightning strikes and lightning-induced fires during thunderstorms. |
| snowman-trails | ALLOW/DENY | Controls snow layers generated beneath snow golems as they walk. |
| snow-fall | ALLOW/DENY | Controls natural accumulation of snow layers during snowfall weather. |
| snow-melt | ALLOW/DENY | Controls snow layers melting due to light sources (torches, lanterns). |
| ice-form | ALLOW/DENY | Controls water surfaces freezing into solid ice blocks in cold biomes. |
| ice-melt | ALLOW/DENY | Controls natural ice melting into water when exposed to warm light levels. |
| frosted-ice-form | ALLOW/DENY | Governs frosted ice creation when players walk on water with Frost Walker enchantment. |
| frosted-ice-melt | ALLOW/DENY | Controls the natural cracking and melting decay stages of frosted ice blocks. |
| crop-growth | ALLOW/DENY | Controls natural growth ticks for wheat, carrots, potatoes, beetroots, and melon stems. |
| soil-dry | ALLOW/DENY | Controls hydrated farmland dehydrating back into ordinary dirt when unwatered. |
| leaf-decay | ALLOW/DENY | Controls natural leaf despawning and sapling drops when disconnected from logs. |
| grass-growth | ALLOW/DENY | Controls spreading of grass and mycelium to adjacent unlit dirt blocks. |
| mushroom-growth | ALLOW/DENY | Governs natural spreading and stem growth of red and brown mushrooms. |
| rock-growth | ALLOW/DENY | Governs growth of dripstone blocks and pointed dripstone stalactites/stalagmites. |
| sculk-growth | ALLOW/DENY | Governs sculk catalyst propagation and sensor/shrieker generation upon entity death. |
| coral-fade | ALLOW/DENY | Controls alive coral blocks dying into dead coral when exposed outside water. |
| copper-fade | ALLOW/DENY | Controls weathering, oxidation, and green patina progression on unwaxed copper blocks. |
| weather-clock | ALLOW/DENY | Locks visual client weather inside city borders (CLEAR, RAIN, THUNDER). |
| time-lock | ALLOW/DENY | Locks client sky time inside city borders (e.g. DAY, NOON, NIGHT, MIDNIGHT). |
Crystals are socketable modular items placed into city cores to provide custom team perks, potion buffs, skill bonuses, flight, death protection, or raid resistance. Each file in plugins/UltraCities/crystals/*.yml defines an independent crystal.
Defines base item material, optional player head Base64 value, display name with HEX color codes, lore lines, visual glow, and minimum required city level to socket the crystal.
material: AMETHYST_SHARD
# value: "" # Optional player head Base64 value
name: "cf745a&lOmni-Crystal &7(Tier 3)"
lore:
- "&7Grants active buffs to members inside territory."
- ""
- " &8| &7Required Level: &f{required-level}"
- " &8| &7Remaining Uses: &f{remaining-uses}"
glow: true
required-city-level: 3
Controls when the crystal mechanics are active: ALWAYS (active 24/7), RAID_ONLY (activates only during active global raid events), or OUTSIDE_RAID (active during peaceful times only).
# Options: ALWAYS, RAID_ONLY, or OUTSIDE_RAID
activation-mode: ALWAYS
List of crystal IDs that cannot coexist in the same city core. Compatibility is enforced bi-directionally: listing guardian in speed also prevents installing speed while guardian is present.
incompatible-with:
- speed_crystal
- guardian_crystal
Applies continuous Bukkit potion effects to the configured audience while within city territory. Supports potion amplifier levels, ambient mode, and particle toggles.
effects:
audience: MEMBERS # ALL, MEMBERS, NON_MEMBERS, OWNERS, NON_OWNERS
list:
- type: SPEED
level: 2
ambient: true
particles: false
- type: REGENERATION
level: 1
ambient: true
particles: true
Configures custom XP gain multipliers for specified skill groups and accelerates natural mana regeneration for players inside the city.
aura-skills:
audience: MEMBERS
xp-multipliers:
- skills: [MINING, FORAGING, FARMING]
multiplier: 2.0
- skills: [COMBAT]
multiplier: 1.5
mana-regeneration:
multiplier: 1.25
Restricts custom enchantments from AdvancedEnchantments from activating inside city territory for the target audience. Supports wildcard "*" to deny all custom enchantments.
advanced-enchantments:
audience: NON_MEMBERS
denied:
- TRENCH
- TELEPATHY
- EXPLOSIVE
Prohibits specified item materials and consumables from being used, drunk, or thrown inside city borders by the configured audience.
blocked-items:
audience: NON_MEMBERS
materials:
- ENDER_PEARL
- CHORUS_FRUIT
- LAVA_BUCKET
- BOW
Accelerates natural crop age steps for configured ageable vegetation inside city boundaries without altering the server-wide tick rate.
random-tick:
multiplier: 2.5
blocks:
- WHEAT
- CARROTS
- POTATOES
- BEETROOTS
- NETHER_WART
- SUGAR_CANE
When enabled, completely freezes natural hunger exhaustion, sprint depletion, and starvation for the designated audience while inside the city.
hunger:
enabled: true
audience: MEMBERS
Enables creative flight within city borders. Includes a configurable border exit warning with titles, actionbars, audio ticks, and grace countdown before revoking flight.
flight:
enabled: true
audience: MEMBERS
exit-warning:
enabled: true
duration-seconds: 3
messages:
title: "&c&lFlight disabled in &f{seconds}s"
subtitle: "&7Return to &f{city} &7to keep flying."
sound:
enabled: true
type: BLOCK_NOTE_BLOCK_HAT
volume: 0.35
pitch: 1.2
Intercepts lethal damage like a Totem of Undying, restoring player health to health-hearts with particle animations and sound effects. Supports cooldowns and optional finite consumable uses.
death-protection:
enabled: true
audience: MEMBERS
cooldown-seconds: 300
health-hearts: 4.0
sound: ITEM_TOTEM_USE
particles: true
finite-uses:
enabled: true
max-uses: 5
Adds extra hit durability to the city's blocks during global raids. Installed crystals stack their hit resistances additively with the city core level baseline.
raid-block-resistance:
additional-hits: 2
Click the dropdown below to view a complete, commented example.yml containing every single crystal section ready for copy-pasting.
# ==============================================================================
# UltraCities - Comprehensive Crystal Template (example.yml)
# Place in plugins/UltraCities/crystals/example.yml
# ==============================================================================
enabled: true
material: AMETHYST_SHARD
# Optional custom player head base64 value (leave empty if using normal material)
# value: ""
name: "cf745a&lOmni-Crystal &7(Master Tier)"
lore:
- "&7Grants multiple active buffs to city members,"
- "&7accelerates crop growth and protects during raids."
- ""
- " &8| &7Required Level: &f{required-level}"
- " &8| &7Remaining Uses: &f{remaining-uses}"
glow: true
required-city-level: 3
# Activation mode: ALWAYS, RAID_ONLY or OUTSIDE_RAID
activation-mode: ALWAYS
# Mutually exclusive crystals (cannot be installed at the same time)
incompatible-with:
- speed_crystal
- defense_crystal
# 1. Potion Effects Configuration
effects:
audience: MEMBERS
list:
- type: SPEED
level: 2
ambient: true
particles: false
- type: REGENERATION
level: 1
ambient: true
particles: true
# 2. Death Protection (Undying Totem Interception)
death-protection:
enabled: true
audience: MEMBERS
cooldown-seconds: 300
health-hearts: 4.0
sound: ITEM_TOTEM_USE
particles: true
finite-uses:
enabled: true
max-uses: 5
# 3. Flight inside city borders
flight:
enabled: true
audience: MEMBERS
exit-warning:
enabled: true
duration-seconds: 3
messages:
title: "&c&lFlight disabled in &f{seconds}s"
subtitle: "&7Return to &f{city} &7to keep flying."
sound:
enabled: true
type: BLOCK_NOTE_BLOCK_HAT
volume: 0.35
pitch: 1.2
# 4. AuraSkills Multipliers (Optional Integration)
aura-skills:
audience: MEMBERS
xp-multipliers:
- skills: [MINING, FORAGING, FARMING]
multiplier: 2.0
- skills: [COMBAT]
multiplier: 1.5
mana-regeneration:
multiplier: 1.25
# 5. Crop Growth Acceleration (Random Ticks)
random-tick:
multiplier: 2.5
blocks:
- WHEAT
- CARROTS
- POTATOES
- BEETROOTS
- NETHER_WART
- SUGAR_CANE
# 6. Hunger & Exhaustion Cancellation
hunger:
enabled: true
audience: MEMBERS
# 7. Blocked Items for Non-Members
blocked-items:
audience: NON_MEMBERS
materials:
- ENDER_PEARL
- CHORUS_FRUIT
- LAVA_BUCKET
# 8. AdvancedEnchantments Restriction
advanced-enchantments:
audience: NON_MEMBERS
denied:
- TRENCH
- TELEPATHY
# 9. Raid Block Durability Bonus (Active during raids)
raid-block-resistance:
additional-hits: 2
Shields defend cities against outsider block breaking, crystal theft, and destruction during global raid events. Each file in plugins/UltraCities/shields/*.yml defines a distinct shield tier with its own duration, appearance, and multi-currency cost.
Defines physical shield item appearance: material (e.g. SHIELD or PLAYER_HEAD), optional Base64 head texture, display name, and lore formatting. Supports placeholders like {duration}, {vault-amount}, and {currency-<id>-amount}.
enabled: true
material: SHIELD
# value: "" # Optional player head Base64 value
name: "cf745a&lFortress Shield &7(12 Hours)"
lore:
- "&7Grants complete immunity against raid destruction,"
- "&7block breaking, and crystal theft."
- ""
- " &8| &7Duration: &f{duration}"
- " &8| &7Cost: &e{vault-amount} {vault-name}"
Total protection duration in seconds (e.g. 3600 for 1 hour, 43200 for 12 hours, 86400 for 24 hours). While active, the city is completely immune to outsider raid damage.
# 43200 seconds = 12 hours
duration-seconds: 43200
Payment engine supporting Vault economy, ExcellentEconomy custom currencies, and physical item requirements. Supports mode: ALL (charges all enabled payment groups) or mode: ANY (accepts the first affordable group).
cost:
enabled: true
mode: ALL # Options: ALL or ANY
vault:
enabled: true
amount: 5000.0
display-name: "&eCoins"
excellent-economy:
enabled: true
currencies:
- id: gems
amount: 25.0
display-name: "&bGems"
items:
enabled: true
requirements:
- material: NETHERITE_INGOT
amount: 1
- material: DIAMOND
amount: 16
Controlled via guis/shields.yml. Menus refresh automatically once per second, updating live {shield-remaining} countdowns without reopening. The dynamic [REMOVE-SHIELD] button appears for city owners to dismiss active protection.
# Inside plugins/UltraCities/guis/shields.yml
shield-display:
active:
material: ENCHANTED_BOOK
glow: true
lore:
- "&a&lCURRENTLY ACTIVE"
- "&7Expires in: &e{shield-remaining}"
blocked:
lore:
- "&cAnother shield is currently active."
Click the dropdown below to view a complete, commented example.yml containing every configurable shield option.
# ==============================================================================
# UltraCities - Comprehensive Shield Template (example.yml)
# Place in plugins/UltraCities/shields/example.yml
# The file name (without .yml) is the persistent shield ID.
# ==============================================================================
enabled: true
material: SHIELD
# value: "" # Optional player head Base64 value
name: "cf745a&lFortress Shield &7(12 Hours)"
lore:
- "&7Grants complete immunity against raid destruction,"
- "&7block breaking, and crystal theft."
- ""
- " &8| &7Duration: &f{duration}"
- " &8| &7Vault Price: &e{vault-amount} {vault-name}"
- " &8| &7Gems: &b{currency-gems-amount} {currency-gems-name}"
# Protection duration in seconds (43200 seconds = 12 hours)
duration-seconds: 43200
# Multi-currency cost configuration
cost:
enabled: true
# mode: ALL (requires every enabled group) or mode: ANY (first affordable group)
mode: ALL
# Standard Vault Economy
vault:
enabled: true
amount: 5000.0
display-name: "&eCoins"
# ExcellentEconomy Custom Currencies
excellent-economy:
enabled: true
currencies:
- id: gems
amount: 25.0
display-name: "&bGems"
- id: tokens
amount: 5.0
display-name: "&6Tokens"
# Physical Item Payment Requirements
items:
enabled: true
requirements:
- material: NETHERITE_INGOT
amount: 1
- material: DIAMOND
amount: 16
Persistent 3D subzones allow players to carve out plots within a city, assign independent flags, manage local members, or list land for sale on the open market.
Administrators grant the selection wand with /city subzone wand <player>. Left-click selects corner one and right-click selects corner two. A temporary 3D particle wireframe traces all 12 edges in real-time.
Subzone owners can list plots with /uc subzone sell [name], choose their target currency (Vault or ExcellentEconomy), and enter the sale price into chat. Prospective buyers inspect and complete purchases through guis/subzone-buy-confirm.yml, transferring ownership atomically.
Subzone flags take full priority over parent-city flags within the cuboid boundaries. Buyers enjoy full autonomy, and parent-city owners are treated as visitors inside the plot until explicitly granted local permissions.
Events are server-wide gameplay states configured in plugins/UltraCities/events/*.yml. Events persist across server restarts and provide live bossbars, broadcast audio, raid sieges, and booster multipliers.
Defines unique command identifier, event type (RAID or BOOSTER), and priority number (higher priority overrides conflicts when multiple events run simultaneously).
id: example_raid
type: RAID # Options: RAID or BOOSTER
enabled: true
priority: 10 # Highest priority wins in case of conflicting forced flags
Plays Bukkit sound effects to all connected players on sounds.started and sounds.ended with independent volume and pitch configuration.
sounds:
started:
enabled: true
sound: BLOCK_BEACON_ACTIVATE
volume: 0.8
pitch: 0.75
ended:
enabled: true
sound: UI_TOAST_CHALLENGE_COMPLETE
volume: 0.8
pitch: 1.0
Renders a live bossbar across player screens displaying title, custom color (RED, PURPLE, BLUE, GREEN, YELLOW, PINK, WHITE), style overlay, and live {remaining} countdown.
bossbar:
enabled: true
title: "cf745a&lSIEGE OF CITIES &8| &f{remaining}"
color: RED # RED, PURPLE, BLUE, GREEN, YELLOW, PINK, WHITE
overlay: PROGRESS # PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, NOTCHED_20
Controls block destruction during raid events. Supports WHITELIST (only listed blocks can be broken) or BLACKLIST (all blocks except listed can be broken), item drops, and anti-macro packet hit cooldowns.
breaking:
enabled: true
mode: BLACKLIST # Options: WHITELIST or BLACKLIST
blocks:
- BEDROCK
- BARRIER
- END_PORTAL_FRAME
- COMMAND_BLOCK
drop-items: true
hit-cooldown-millis: 250 # Anti-macro hit protection
When enabled, raiders can infiltrate unshielded city cores during active raids and steal installed crystals by interacting with the physical core block.
crystals:
stealable: true
Temporarily overrides city flags across all unshielded cities while the event is running. When the event ends, all cities return to their normal configured rules automatically. Active shields are immune to all overrides.
forced-flags:
block-break:
state: ALLOW
audience: NON_MEMBERS
block-place:
state: DENY
audience: NON_MEMBERS
chest-access:
state: ALLOW
audience: NON_MEMBERS
pvp:
state: ALLOW
audience: ALL
tnt:
state: DENY
audience: NON_MEMBERS
Configured when type: BOOSTER. Multiplies AuraSkills XP gains and accelerates crop growth ticks within cities. Multiple concurrent boosters stack multiplicatively.
aura-skills:
xp-multipliers:
- skills: [MINING, FORAGING, FARMING]
multiplier: 2.0
- skills: [COMBAT]
multiplier: 1.5
random-tick:
multiplier: 3.0
blocks:
- WHEAT
- CARROTS
- POTATOES
- NETHER_WART
Formatted broadcast announcements sent to all players when the event starts and ends. Supports {duration}, {remaining}, and color codes.
messages:
prefix: "&8[cf745aRaid Event&8] "
started:
- "cf745aA server-wide city raid has commenced for &f{duration}cf745a!"
- "&7Unshielded cities are now vulnerable to block breaking and crystal theft."
ended:
- "&aThe city raid event has concluded."
- "&7All city protections have returned to their normal configured rules."
Click the dropdown below to view a complete, commented example.yml containing every configurable event section.
# ==============================================================================
# UltraCities - Comprehensive Event Template (example.yml)
# Place in plugins/UltraCities/events/example.yml
# ==============================================================================
# Unique identifier used by commands: /city event start example <duration>
id: example_raid
type: RAID # Options: RAID or BOOSTER
enabled: true
priority: 10 # Highest priority wins in case of conflicting forced flags
# Global audio notifications played to all online players
sounds:
started:
enabled: true
sound: BLOCK_BEACON_ACTIVATE
volume: 0.8
pitch: 0.75
ended:
enabled: true
sound: UI_TOAST_CHALLENGE_COMPLETE
volume: 0.8
pitch: 1.0
# Live bossbar display shown across player screens
bossbar:
enabled: true
title: "cf745a&lSIEGE OF CITIES &8| &f{remaining}"
color: RED # RED, PURPLE, BLUE, GREEN, YELLOW, PINK, WHITE
overlay: PROGRESS # PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, NOTCHED_20
# Raid Destruction Mechanics (Applicable when type is RAID)
breaking:
enabled: true
# WHITELIST allows only specified blocks; BLACKLIST allows all except listed blocks
mode: BLACKLIST
blocks:
- BEDROCK
- BARRIER
- END_PORTAL_FRAME
- COMMAND_BLOCK
drop-items: true
hit-cooldown-millis: 250 # Anti-macro protection for block hits
# Crystal theft mechanic from unshielded city cores
crystals:
stealable: true
# Temporary flag overrides during the event (Shielded cities are immune)
forced-flags:
block-break:
state: ALLOW
audience: NON_MEMBERS
block-place:
state: DENY
audience: NON_MEMBERS
chest-access:
state: ALLOW
audience: NON_MEMBERS
pvp:
state: ALLOW
audience: ALL
tnt:
state: DENY
audience: NON_MEMBERS
# Event Broadcast Announcements
messages:
prefix: "&8[cf745aRaid Event&8] "
started:
- "cf745aA server-wide city raid has commenced for &f{duration}cf745a!"
- "&7Unshielded cities are now vulnerable to block breaking and crystal theft."
ended:
- "&aThe city raid event has concluded."
- "&7All city protections have returned to their normal configured rules."
Use /city, /uc, /cities, or /ultracities. Required arguments use < >; optional arguments use [ ]. City commands normally target the protection at your location.
| Command | Description |
|---|---|
| /city [help] | Shows the command guide. The argument is optional. |
| /city menu | Opens the main panel for the city at your location. |
| /city list | Opens your owned/co-owned protections with coordinates and prints them in chat. The default city-item action travels to its home; the multiline city-list message is configurable. |
| /city list all | Opens the public city directory; coordinates are hidden by default and can be added to its GUI configuration. |
| /city info | Shows configurable city-info messages for the protection at your location, including owners, level, capacities and coordinates. |
| /city sethome | Owner only: saves your safe current position and facing as the city's shared home when home.enabled is true for its block type. |
| /city delhome | Owners/co-owners only, inside the city: deletes its saved home without removing the protection. Requires ultracities.command.delhome (default true, ownership still enforced). Works even when homes are disabled. Reload/restart does not recreate it; use /city sethome once homes are enabled. Trips to a changed or deleted home are cancelled. |
| /city home [city name|city UUID] | Owners/co-owners can travel when home.enabled is true. Full members also qualify when home.allow-members is true (the default); individual flags alone grant no home access. Autocomplete suggests plain names and UUIDs across all accessible owned and permitted member cities, including multi-word names. Without a target, selects the current accessible city or the only accessible city; multiple candidates require a choice. New cities automatically save a home above the core when home.auto-set-on-place is true. Defaults to a 3-second warmup cancelled by movement/jumping or actual damage, not looking around. Configure teleportation in config.yml. Access/settings, safety and home coordinates are rechecked before completion; deleting/changing a home cancels its pending journey. |
| /city addowner <player> | Owner only: grants another known player full city ownership, including deletion. Counts toward their protection limits, not member slots; purchased-subzone rules remain applicable. |
| /city border | Temporarily shows the current city's particle border. |
| /city hologram [on|off|toggle] | Controls your personal view of city holograms; omitting the argument toggles it. |
| /city rename <new name> | Owner only: renames the current city. Color codes and any configured cost, cooldown, or confirmation apply. |
| /city tag <tag|clear> | Owner only: sets or clears the city's short tag. |
| /city add <player> | Owner only: adds a full-access member, subject to the city's member limit. |
| /city remove <player> | Owner only: removes a city member. |
| /city flags | Owner only: opens the city's editable flags panel. |
| /city flags <player> | Owner only: opens an existing member's individual flags panel. |
| /city flag <flag> <allow|deny> [audience] | Owner only: sets a city flag to a state and optional audience allowed by that protection block's configuration. |
| /city userflags <player> | Owner only: opens an existing member's individual flags panel. |
| /city userflags <player> <flag> <allow|deny> | Owner only: directly changes one of that member's individual flags. |
| /city userflag <player> <flag> <allow|deny> | Singular alternative for changing one individual flag. |
| /city nearby request <player> | Asks another online city owner to allow placement inside the minimum city distance. |
| /city nearby accept <player> | Accepts that player's nearby-placement request. |
| /city nearby deny <player> | Declines that player's nearby-placement request. |
| Command | Description |
|---|---|
| /city subzone | Opens settings for the subzone at your location. |
| /city subzone <name> | Opens the named subzone's settings panel. |
| /city subzone menu | Opens the parent city's subzone browser; requires access to the main city. |
| /city subzone list | Lists the parent city's subzones; requires access to the main city. |
| /city subzone create <name> | Creates a subzone from two wand-selected positions, subject to limits and creation cost. |
| /city subzone delete <name> | Deletes a subzone you are allowed to manage. |
| /city subzone cancel | Clears your wand selection. |
| /city subzone sell [name] | Opens sale setup for the named or current subzone. |
| /city subzone unsell [name] | Removes the sale listing; unlist is an alias. |
| /city subzone buy [name] | Opens the purchase confirmation panel. |
| /city subzone flags [name] | Opens the named or current subzone's independent flags panel. |
| /city subzone add <player> | Adds a player to the subzone at your location and opens their individual flags panel. |
| /city subzone remove <player> | Removes a player from the subzone at your location. |
| Command | Description |
|---|---|
| /city give <player> <type> [amount] | Gives a configured protection block item to a player. |
| /city crystal give <player> <crystal> [amount] [silent] | Gives a configured crystal; silent suppresses the recipient notification. |
| /city subzone wand <player> | Gives the subzone selection wand to an online player. |
| /city event start <event-id> <duration> | Starts a configured global raid or booster. Duration accepts seconds or an s, m, h, or d suffix, such as 30m. |
| /city event stop <event-id> | Stops that global event. |
| /city reload | Reloads UltraCities configuration. |
| /city admin [help] | Shows the operator-only administration guide. |
| /city admin menu | Opens the main panel of the city at your location with administrator access. |
| /city admin flags | Opens that city's flags panel with administrator access. |
| /city admin flags <world> <flag> <allow|deny> <audience> | Sets a flag across cities in one world, skipping configurations that do not allow the chosen state or audience. |
| /city admin protections <player> | Browses a known player's owned/co-owned protections with coordinates and teleport controls. |
| /city admin teleport <player> <city name|city UUID> | Travels to one of that player's protections, using its saved home or a safe position above its core. Bypasses the home warmup. |
| /city admin add <player> | Adds a member to the current city without checking its member limit and opens individual flags. |
| /city admin remove <player> | Removes a member from the current city. |
| /city admin owner <player> | Transfers primary ownership of the current city. Other additional owners are retained. |
| /city admin upgrade [levels|max] | Advances the current city's level without payment or upgrade requirements. |
| /city admin delete | Deletes the city at your location after repeating the command to confirm within 30 seconds. |
| /city admin subzone create <name> | Creates a subzone from your current wand selection with administrator authority. |
| /city admin subzone delete <name> | Deletes a named subzone in the current city. |
| /city admin subzone add <name> <player> | Adds a player to a named subzone and opens individual flags. |
| /city admin subzone remove <name> <player> | Removes a player from a named subzone. |
| /city admin subzone flags <name> | Opens flags for a named subzone. |
| /city admin cleanup <world|all> <owner|everyone> <duration> [confirm] | Previews inactivity cleanup; repeat with confirm within 60 seconds to delete. owner checks only the owner; everyone checks the owner and members. Duration accepts h, d, w, mo, or y, such as 90d. An audit log is written under data/. |
| Permission | Purpose |
|---|---|
| ultracities.command.<path> | Command permissions follow the command path, such as ultracities.command.menu, ultracities.command.subzone.create, and ultracities.command.event.start. Player command nodes default to everyone; give, crystal, event, wand, reload, and admin nodes default to operators. |
| ultracities.admin | Administrative capabilities and child permissions. The /city admin branch additionally checks operator status. |
| ultracities.command.delhome | Allows the delete-home command; defaults to everyone, but the player must still own/co-own the city at their location. Does not grant deletion access to members or visitors. |
| ultracities.bypass | Bypasses protected-region restrictions; defaults to operators. |
| ultracities.protections.limit.<amount> | Total owned-protection limit; ultracities.protections.limit.unlimited removes it. |
| ultracities.protections.limit.world.<world>.<amount> | Per-world owned-protection limit; use .unlimited for one world or ultracities.protections.limit.world.unlimited for all worlds. |
Install PlaceholderAPI before UltraCities starts. The bundled ultracities expansion registers automatically; no eCloud download is required for UltraCities placeholders. Other expansions used in conditions must be installed separately.
Boolean placeholders return true/false, except the minimum-owned-level check which returns yes/no. Ownership includes additional owners. Unlimited limits return the literal unlimited.
| Placeholder | Result |
|---|---|
| %ultracities_has_city% | true if a primary city can be selected, otherwise false. |
| %ultracities_city_role% %ultracities_current_city_role% | Role: owner, member, visitor (current city only), or none. Individual-flag users are still reported as member. |
| %ultracities_owned_protections% %ultracities_protection_count% %ultracities_number_of_protections% | Number of owned/co-owned city protections. The last two names are aliases. |
| %ultracities_member_protections% | Associated cities where the player is not an owner. |
| %ultracities_associated_protections% | Number of city memberships, including ownership. |
| %ultracities_protection_limit% %ultracities_protections_remaining% | Total ownership limit and remaining allowance; unlimited when unrestricted. |
| %ultracities_world_protection_count% %ultracities_world_protection_limit% %ultracities_world_protections_remaining% | Owned count, limit and remaining allowance in the online player's current world. |
| %ultracities_city_level_6% | yes if the player owns/co-owns a city at level 6 or higher; otherwise no. Replace 6 with any positive integer. All worlds, offline players supported, pending city saves excluded. |
| %ultracities_city_amount_level_6% | Number of owned/co-owned cities at level 6 or higher. Replace 6 with any positive integer; memberships without ownership do not count. |
| %ultracities_total_cities% %ultracities_total_protections% | Server-wide number of cities; aliases. |
| %ultracities_total_memberships% | Server-wide sum of stored city member entries (not distinct players). |
| %ultracities_active_shields% | Server-wide number of cities with an active shield. |
| %ultracities_raid_active% | true while a global raid is active, otherwise false. |
city_ selects an associated city containing the player, otherwise their highest-level owned city, then their highest-level membership. current_city_ always describes the physical city at an online player's location, including for visitors. Every city suffix below also supports current_city_, for example %ultracities_current_city_members%. Without a city, city-scoped values return an empty string. Standalone counts return 0. Current-subzone values require an online player.
| Placeholder | Result |
|---|---|
| %ultracities_city_name% %ultracities_city_name_plain% | Configured city name, with formatting or without formatting. |
| %ultracities_city_tag% %ultracities_city_tag_plain% %ultracities_city_has_tag% | Configured tag, plain tag, and true/false indicating whether a tag is set. |
| %ultracities_city_id% %ultracities_city_type% | City UUID and protection block ID. |
| %ultracities_city_owner% %ultracities_city_owner_uuid% | Primary owner's player name and UUID. Additional owners retain full ownership but do not replace these primary-owner values. |
| %ultracities_city_level% %ultracities_city_max_level% | Current city level and the maximum level configured for its block type. |
| %ultracities_city_radius% %ultracities_city_configured_radius% | Effective radius and the configured level radius before any nearby-city limitation. |
| %ultracities_city_members% %ultracities_city_members_including_owner% %ultracities_city_max_members% | Counted members, counted members plus the primary owner, and maximum member capacity. Additional owners do not consume member slots. |
| %ultracities_city_storage_rows% %ultracities_city_storage_slots% | Shared storage rows and slots. |
| %ultracities_city_crystal_slots% %ultracities_city_installed_crystals% | Crystal socket capacity and number of installed crystals. |
| %ultracities_city_raid_hits% | Required raid block hits, including the currently applicable crystal bonus. |
| %ultracities_city_raid_active% | true if a raid applies to this city, otherwise false. |
| %ultracities_city_subzones% %ultracities_city_max_subzones% %ultracities_city_max_subzone_blocks% | Subzone count, maximum number of subzones and maximum blocks per subzone. |
| %ultracities_city_shield_active% %ultracities_city_shield_type% | true/false shield status and purchased shield ID (empty if none). |
| %ultracities_city_shield_remaining% %ultracities_city_shield_remaining_seconds% | Remaining shield time as formatted text or seconds. |
| %ultracities_city_world% %ultracities_city_x% %ultracities_city_y% %ultracities_city_z% | World name and protection core coordinates. |
| %ultracities_city_flag_<flag>% %ultracities_city_flag_<flag>_audience% | Configured allow/deny and audience for a flag; for example city_flag_block-break. Also accepts underscores in flag names. Audiences: all, members, non-members, owners, non-owners. These are saved city rules, not a per-player effective permission check or event override. |
| Placeholder | Result |
|---|---|
| %ultracities_current_subzone_name% %ultracities_current_subzone_id% | Name and UUID of the subzone at the online player's location. |
| %ultracities_current_subzone_owner% %ultracities_current_subzone_owner_uuid% | Subzone owner's player name and UUID. |
| %ultracities_current_subzone_members% | Number of stored subzone member entries. |
| %ultracities_current_subzone_blocks% | Inclusive 3D subzone volume in blocks. |
| %ultracities_current_subzone_for_sale% | true if the subzone is for sale, otherwise false. |
| %ultracities_current_subzone_sale_price% | Sale price; 0 when there is no current subzone. |
| Placeholder | Result |
|---|---|
| %ultracities_event_<id>_active% | true if the specified configured event is active, otherwise false. |
| %ultracities_event_<id>_remaining_seconds% | Remaining time of the specified event in seconds. Event IDs containing hyphens may also use underscores in the placeholder. |
UltraPortals is a customizable portal system for Paper 1.21 through 26.3. Create teleport regions with a selection wand, choose weighted destinations, run commands or transfer players between servers, and customize access rules, opening windows, glowing borders, particles and sounds.
Select two corners with the wand to create a portal. Send players to named or weighted random destinations, run commands without teleporting, or connect them to a BungeeCord server.
Control entry with permissions, economy balances and PlaceholderAPI conditions. Charge money or exact inventory items, and present configurable requirement and cost checklists.
Open portals for a set duration or number of successful entries. Configure player or global cooldowns, and make closed portals completely inactive when desired.
Design custom glowing silhouettes or rectangles with state colors and smooth transitions. Add permanent, entry and arrival particles, positional sounds and portal ambience.
Requirements, files, configuration and migration.
UltraPortals-1.0.0.jar in plugins/, then start it. No mandatory companion plugin is required; SQLite is bundled.plugins/UltraPortals/config.yml and use /portal reload. For a JAR update, back up the complete plugin folder while stopped, replace the JAR and restart. Existing files are preserved.| Optional integration | Purpose |
|---|---|
| Vault + an economy provider | Balance requirements and money costs |
| CoinsEngine / ExcellentEconomy | Named currencies |
| PlaceholderAPI + relevant expansions | Placeholder conditions, messages and exported values |
| BungeeCord-compatible proxy | Server transfers; enable proxy.enabled |
| File or section | Purpose |
|---|---|
| portals/name.yml | Region, actions, access rules, glow and local messages |
| destinations/name.yml | World, position, viewing direction, arrival effects and commands |
| particles-effects/name.yml | Reusable particle definitions |
| messages.yml | Global messages and display channels |
| data/players.db | SQLite cooldowns, visits, refunds and opening state |
| defaults | Values copied into new portals/destinations only |
| teleport | Async chunk-load limits, timeout, terrain generation and safe arrival checks |
| effects / glow / sounds | Shared packet, entity and animation budgets |
| denial | Default pushback, denial sound and message interval |
The default trigger is ALL; default particles, sounds and general glow are disabled. Main YAML files contain comments for every setting. Changing defaults does not rewrite existing portals. Invalid reloads retain the previous configuration.
New-portal defaults · config.yml
defaults:
trigger-block: ALL
glow:
enabled: false
color: '#B03AFF'
view-distance: 32Merge this fragment into the existing file; keep its other settings.
Keep its data in the sibling plugins/AdvancedPortals/ folder; it does not need to be running.
Command example
/portal import advancedportals preview
/portal import advancedportals apply
Imports support portals/, destinations/ and desti/ files with .yml/.yaml extensions, legacy aggregate YAML and config.yml/config.yaml. Source files and existing UltraPortals files are preserved. Read the report in data/: unsupported rules import disabled for review. Correct them before enabling overlapping portals, and stop AdvancedPortals first.
Case-distinct names such as spawn/Spawn get unique IDs; references are remapped. Keep import.advancedportals.source-name metadata for stable reimports. Portals without a local destination import without entry particles; effects can be added manually afterwards.
Check /portal info <portal> and the console's first validation error. Missing destinations usually mean an unloaded world, an incorrect mapped ID or unsafe/un-generated arrival terrain. For missing effects, check the effect ID, mode, loaded chunks, viewers and configured budgets.
Detection uses a chunk index; destination preparation is asynchronous and bounded. Visuals do not force chunks to remain loaded. Storage errors block travel until restart. Back up the entire folder while stopped, including SQLite sidecars if present. Performance depends on the server workload; no fixed TPS/FPS gain is promised.
Create a region and choose what happens when a player enters.
Command example
/portal create destination spawn
/portal wand
/portal create portal lobby
/portal set portal lobby destination spawn
Create the destination while standing at the arrival point. With the wand, left-click one portal corner and right-click the opposite corner before creating lobby. Bounds include both blocks. The private selection preview lasts 20 seconds and stops when creation succeeds. /portal pos1 and /portal pos2 can select at your feet instead.
Only player movement activates portals. Leaving/re-entering prevents repeated activation while standing inside; arrival protection prevents immediate portal chains. IDs are case-insensitive, saved lowercase, and accept 1–64 letters, numbers, underscores or hyphens.
| Setting | Values |
|---|---|
| triggerblock | ALL, one material, or a list such as AIR,WATER; completion continues after commas |
| cooldown | 10s, 30m, 4h or 0s; player (individual) or global (shared) |
| pushback | on with vertical/horizontal strengths 0..4, off, or inherit |
| name | Display name with spaces, Minecraft colors or HEX |
| enabled | on/off; independent of open-mode |
| protection | on/off for block physics and fluid flow; not a general claim system |
ALL ignores material but does not bypass solid block collision. AIR includes cave/void air. Cooldowns begin after successful activation and survive restarts.
Portal settings · portals/lobby.yml
name: '&#B03AFFLobby'
trigger-block: ALL
destinations: '70:spawn,30:rare'
cooldown:
duration: 10s
scope: playerMerge this fragment into the existing file; keep its other settings.
Command example
/portal set portal lobby destination 70:spawn,30:rare
/portal set portal lobby command add console:say {player} arrived
/portal set destination spawn command add console:say {player} is departing 1
Weighted destinations must exist, have unique names and total exactly 100. Creation saves the exact world, coordinates, yaw and pitch; the world must already be loaded. Use destination none to clear local travel. Deletion is blocked while referenced.
A portal can teleport, run commands, or do both. With no destination, at least one accepted command is required. With both, portal commands run after arrival. Destination commands use priority 1 before teleportation (after preparation/charging) or 0 after arrival, following portal commands. Priority 0 is the default. Player commands retain normal permissions; console commands have console authority. Do not add a leading slash after the sender prefix.
Command example
/portal set portal lobby destination none
/portal set portal lobby server survival
Enable proxy.enabled on a backend using BungeeCord Connect or a compatible proxy channel. The server name must match the proxy configuration. Local destinations and a proxy server cannot coexist; commands can. Use server none to remove it. Connect has no arrival acknowledgement: costs, cooldowns and quotas apply when the request is sent, even if the remote server rejects it.
Timed access, successful-entry limits and inactive closed portals.
Command example
/portal set portal lobby open-mode true
/portal open lobby 5m 10
/portal open lobby forever 5
/portal close lobby 30s
Open-mode is false by default. Enabling it starts closed. An open command starts a new window and resets its count. Closing, expiry or reaching the successful-entry limit ends access. The limit counts activations, not distinct players; failed entries do not consume it.
| Command | Result |
|---|---|
| open lobby | Permanently open, unlimited entries |
| open lobby 5m 10 | Five minutes or ten successful entries |
| open lobby forever 5 | No time limit, five entries |
| close lobby | Closed indefinitely |
| close lobby 30s | Closed for 30 seconds, then permanently open with unlimited entries |
Durations use s/m/h and must be positive. New commands replace previous timers. Opening does not bypass enabled, requirements, costs or cooldowns. Reservations protect quotas during travel preparation; closure invalidates trips not yet admitted. State, counts and absolute deadlines persist through reloads/restarts, including time spent offline.
Command example
/portal set portal lobby open-mode inactive-when-closed true
Default false. With it enabled, closed portals ignore entry: no denial messages, pushback, costs, commands or travel. Permanent particles, ambient pulses and portal physics/vanilla-teleport protection also stop. Physical blocks retain normal Minecraft behavior. Configured state glows and open/close sounds remain independent.
Set it to false for normal closed-portal denial. State labels, timers and counters can be customized in messages.yml and displayed through PlaceholderAPI.
Silent closure · portals/lobby.yml
open-mode: true
open-settings:
inactive-when-closed: trueMerge this fragment into the existing file; keep its other settings.
Permission, balance and placeholder checks with money or item payments.
Command example
/portal set portal lobby requirement add vip permission server.vip
/portal set portal lobby requirement add balance economy vault 100
/portal set portal lobby requirement add level condition %player_level% >= 20
/portal set portal lobby cost add fee economy vault 25
/portal set portal lobby cost add token item 3
All requirements must pass. A balance requirement checks money; an economy cost charges it. For item costs, hold the exact item in the main hand: name, lore, enchantments and supported metadata are preserved. Matching uses Bukkit isSimilar; armor/offhand are excluded. Amounts are integers 1..2304. Repeated costs of the same item/currency are summed.
| Option | Values |
|---|---|
| Economy | vault, coinsengine:currency, excellenteconomy:currency |
| Condition operators | ==, !=, >, <, >=, <= |
| Comparison | Numeric values compare numerically; strings support equality/inequality |
| Limits | Up to 128 requirements and 128 costs per portal |
| Friendly label | Optional label field on each rule in the portal YAML |
Missing currencies/providers or unresolved placeholders deny access. Operators still meet requirements and pay costs. Failed/cancelled travel refunds collected payments; unavailable refunds are queued and can be claimed with /portal refunds. Arbitrary third-party command side effects cannot be undone.
Labeled entry fee · portals/lobby.yml
requirements:
vip:
type: permission
permission: server.vip
label: '&#B03AFFVIP access'
costs:
fee:
type: economy
economy: vault
amount: 25
label: '&#B03AFFTravel fee'Merge this fragment into the existing file; keep its other settings.
Command example
/portal set portal lobby requirement remove vip
/portal set portal lobby cost remove fee
/portal set portal lobby requirement clear
/portal set portal lobby cost clear
Each portal can customize its denial checklist under messages.denial. Put {requirements} and {costs} on separate lines; the plugin expands the full pass/fail list. Format individual rows and labels under details in messages.yml.
Select a shape, position its borders and animate state changes.
Command example
/portal set portal lobby glow edit color #B03AFF
/portal wand
/portal set portal lobby glow save
During glow editing, left-click adds a block and right-click removes one. Shift + left/right-click sets opposite rectangle corners in the same X, Y or Z plane. The preview is private. Repeating edit options preserves pending geometry. Save commits; cancel discards; both restore ordinary portal selection. Clear restores the pending portal outline. World changes, disconnects and reloads cancel editing.
/portal glow edit <portal> [setting value ...] and /portal glow save|cancel|clear remain aliases. Direct settings save immediately; settings after glow edit preview until saved. Color none immediately disables the general glow and ends that player's session, retaining the saved shape.
| Setting after glow | Values / behavior |
|---|---|
| color | All 16 Minecraft names or #RRGGBB; none disables the general glow |
| axis | AUTO preserves the silhouette; X/Y/Z draw its bounding rectangle perpendicular to that world axis |
| plane | CENTER, MIN, MAX, BOTH; NEAR/FAR resolve once using your position |
| placement / distance | INSIDE shrinks, OUTSIDE expands; 0..4 blocks |
| offset-x / offset-y / offset-z | World-axis translations -8..8 blocks |
| thickness | Line width 0.01..0.5 blocks |
| sides | ALL, NONE or a comma-separated border list |
| view-distance | 1..256 blocks; default 64; the complete outline appears together |
Sides are TOP/BOTTOM/LEFT/RIGHT, plus FRONT/BACK for volumes. They use world axes: vertical Z-normal LEFT=-X/RIGHT=+X; X-normal LEFT=-Z/RIGHT=+Z; TOP=+Y/BOTTOM=-Y. Horizontal Y-normal TOP=-Z/BOTTOM=+Z. FRONT=-Z/BACK=+Z. Hidden sides consume no animation time.
AUTO volumes keep twelve outer edges with CENTER; use X/Y/Z for other planes. MIN/MAX depth also moves with inset/expansion; CENTER retains depth. Irregular AUTO outlines resize around their total bounds. Up to 256 selected blocks and 128 merged segments are supported. Thin BlockDisplays retain a small solid body; this is not an invisible particle outline.
Command example
/portal set portal lobby open-mode glow open #B03AFF
/portal set portal lobby open-mode glow close none
/portal set portal lobby open-mode glow open sides TOP,LEFT,RIGHT
/portal set portal lobby open-mode glow animation on 40
/portal set portal lobby open-mode glow animation style CENTER_OUT MIN_X
State overrides apply with open-mode enabled. Color and sides inherit independently; inherit uses the general setting, none hides that state. Explicit state colors work even when the general glow is disabled.
CORNER follows the border from a corner. CENTER_OUT travels both ways from a boundary-edge midpoint. Starting sides: MIN_X/MAX_X/MIN_Y/MAX_Y/MIN_Z/MAX_Z. Duration is 2..200 ticks; 40 = two seconds at 20 TPS. Old colors remain while new ones advance; transitions to/from no glow retract/draw progressively. Animation off makes changes immediate. Temporary overlays share the display cap; low capacity can fall back to existing-line color changes.
Animated purple outline · portals/lobby.yml
open-mode: true
glow:
enabled: true
color: '#B03AFF'
states:
open: '#B03AFF'
close: none
animation:
enabled: true
duration-ticks: 40Merge this fragment into the existing file; keep its other settings.
Command example
/portal set portal lobby glow condition add quiet green %server_online% < 10
/portal set portal lobby glow condition remove quiet
The first matching server-context PlaceholderAPI rule wins; use clear to remove all. Explicit state colors take priority. Unresolved/no-match conditions fall back to the general color.
All lines share one render/tracking origin. Native range includes the outline bounding radius, so large outlines can appear earlier from some directions. Client settings, server tracking and the loaded origin chunk still limit visibility. No player polling or forced chunk loading is added; check final animation appearance with real clients.
Reusable portal animations and positional audio.
Command example
/portal set portal lobby particle-effect PERMANENT portal-bars
/portal set portal lobby particle-effect ON_ENTER arcane
/portal set destination spawn particle-effect arrival
PERMANENT repeats near players; ON_ENTER runs once on validated activation. Both are independent; use none to disable either. Entry particles begin before teleportation/commands and can remain visible if teleportation is cancelled. Destination effects start after successful arrival. Normally closed portals keep permanent effects, except in inactive closed mode.
Effects live in particles-effects/id.yml. Duplicate a preset, edit it and reload. Existing presets are preserved. Destination-only effects have no portal region, so region shapes are skipped there.
| Field | Options |
|---|---|
| type | PLAYER, PORTAL_BOTTOM_CENTER or PORTAL_CENTER; portal types ignore where the player touched the region |
| duration-ticks / interval-ticks | 1..200 / 1..40 |
| layers | 1..8 layers, each with particle, shape and points (1..128) |
| shape | RING, HELIX, SPIRAL, SPHERE, BURST, PORTAL_FILL, PORTAL_BARS, PORTAL_FACES, PORTAL_EXPLODE, PORTAL_IMPLODE, ADVANCEDPORTALS_ENDER |
| Color particles | color, size; DUST_COLOR_TRANSITION also uses to-color |
| Local geometry | radius, height, turns, rotation (radians), expansion, offset, spread and speed |
| PORTAL_BARS | bars 2..32; points must be at least twice bars; cuboids use the outer perimeter |
| PORTAL_FACES | faces: bottom/top/north/south/west/east; direction: inward/outward; travel-distance: 0..16 |
| PORTAL_EXPLODE / IMPLODE | Expand outwards or collapse into the region center |
The permanent PLAYER mode uses the portal center. Region shapes use a fixed point budget; density decreases on large regions. Radius/height are capped at eight blocks for local shapes. Use valid Bukkit particle names for your server; unsupported data-dependent types reject loading. The files contain further preset-specific comments.
YAML example
type: PORTAL_CENTER
duration-ticks: 40
interval-ticks: 2
layers:
streams:
shape: PORTAL_FACES
particle: DUST
color: '#B03AFF'
size: 1.0
points: 64
faces: [bottom, top]
direction: inward
travel-distance: 2
Dense effects increase network/client work. Packet, viewer and animation budgets are shared; excess particles are skipped and no chunks are loaded for visuals.
Command example
/portal set portal lobby sound entity.enderman.teleport 0.8 1.2
/portal set destination spawn sound inherit
/portal set portal lobby open-mode sound close block.beacon.deactivate
/portal set portal lobby ambient-sound block.portal.ambient 0.3 1.0 100 24
Arrival sound plays at the player's resulting location, not at the remote entrance. A destination can inherit, override or silence it with none. Resource-pack keys require their assets. State sounds fire on actual open/close transitions. Ambient arguments are sound, volume, pitch, repeat ticks and range: volume 0..4, pitch 0..2, interval 20..12000, range 1..64 blocks. Inactive closure stops ambient pulses; already playing clips may finish. All sounds default off.
Chat, titles, actionbars and per-portal denial checklists.
Messages are edited in messages.yml. A string/list sends chat; an empty string disables the message. A section can combine chat, title, subtitle and actionbar. Title timings are ticks. Colors accept Minecraft & codes and HEX formats such as &#B03AFF.
YAML example
teleported:
chat: ['&aYou arrived at {destination}.']
title: '&#B03AFFWelcome!'
subtitle: '&7Enjoy your stay, {player}.'
actionbar: '&aTravel complete.'
fade-in: 10
stay: 60
fade-out: 10
A portal's messages section overrides global messages of the same name. Remove a local key to inherit it again. Requirement/cost labels are optional fields on each rule; details in messages.yml controls individual checklist rows.
YAML example
messages:
denial:
chat:
- '&#B03AFF{name}'
- '&fEntry requirements:'
- '{requirements}'
- '&fTravel costs:'
- '{costs}'
Put {requirements} and {costs} on whole lines so they expand into complete pass/fail checklists. Common internal substitutions: {prefix}, {player}, {uuid}, {portal}, {name}, {destination}, {remaining}. Opening messages also expose {state}, {open-time}, {entered}/{players} and {maximum}/{max-players}.
External %placeholders% require PlaceholderAPI and their expansions. State labels live under open-mode: open, closed, disabled, permanent and unlimited. Existing customized message files are preserved on updates; merge new defaults from the shipped file when needed.
The supported command reference, without repeated walkthroughs.
Use /portal, /portals or /ultraportals. edit is an alias for set, including destination settings. Required arguments use < >; optional arguments use [ ]. Names containing spaces are supported only where a display name or command is expected.
| Command | Action |
|---|---|
/portal help |
Show command help |
/portal wand; /portal pos1; /portal pos2 |
Select portal corners |
/portal create portal <name> |
Create from your selection |
/portal create destination <name> |
Save your position/orientation |
/portal info <portal>; /portal show <portal> |
Inspect settings or preview bounds |
/portal list [portals/destinations/effects] |
List saved IDs |
/portal delete <portal/destination> <name> |
Delete an entry; referenced destinations are protected |
/portal reload |
Reload YAML together |
/portal refunds |
Claim queued refunds |
/portal import advancedportals [preview/apply] |
Preview or apply migration |
Prefix every row below with /portal set portal
| Setting | Action |
|---|---|
destination <id / weighted-list / none> |
Set or clear local travel |
server <name / none> |
Set or clear proxy travel |
triggerblock <ALL / material-list> |
Choose activation materials |
cooldown <duration> [player/global] |
Set successful-activation cooldown |
pushback <on/off/inherit> [vertical] [horizontal] |
Configure denied-entry pushback |
name <display name> |
Change the display name |
enabled <on/off>; protection <on/off> |
Control activation or physics protection |
command add <console:command / player:command> |
Add a command; destination optional |
command remove <index>; command clear |
Remove commands; indices start at 1 |
requirement add <id> permission <node> |
Require a permission |
requirement add <id> economy <provider> <amount> |
Check a balance without charging |
requirement add <id> condition <placeholder> <operator> <value> |
Require a PAPI comparison |
cost add <id> economy <provider> <amount> |
Charge money |
cost add <id> item <amount> |
Copy/charge the held item |
requirement/cost remove <id>; requirement/cost clear |
Remove rules |
particle-effect <PERMANENT/ON_ENTER> <effect/none> |
Assign an independent particle mode |
sound <key/none> [volume] [pitch] |
Set arrival sound |
ambient-sound <key/none> [volume] [pitch] [ticks] [range] |
Repeat positional ambient audio |
open-mode <true/false> |
Enable opening windows |
open-mode inactive-when-closed <true/false> |
Ignore entry while closed |
open-mode sound <open/close> <key/none> [volume] [pitch] |
Set state sounds |
open-mode glow <open/close> <color/inherit/none> |
Override state color |
open-mode glow <open/close> sides <list/inherit> |
Override state borders |
open-mode glow animation <on/off> [ticks] |
Enable transitions and duration |
open-mode glow animation style <CORNER/CENTER_OUT> [side] |
Choose the wave path |
Prefix these rows with /portal set portal
| Setting | Action |
|---|---|
edit [setting value ...] |
Start/update the private editing session |
save; cancel; clear |
Save, discard or reset pending selection |
color <color/none> |
Set/disable the general glow |
view-distance <blocks> |
Whole-outline visibility range |
axis <AUTO/X/Y/Z>; plane <CENTER/MIN/MAX/BOTH/NEAR/FAR> |
Choose outline plane |
placement <INSIDE/OUTSIDE>; distance <blocks> |
Resize/place the border |
offset-x/offset-y/offset-z <value>; thickness <value> |
Shift lines or change width |
sides <ALL/NONE/list> |
Select visible borders |
condition add <id> <color> <placeholder> <operator> <value> |
Add a general color rule |
condition remove <id>; condition clear |
Remove color rules |
Original aliases remain: /portal glow edit <portal> [setting value ...] and /portal glow save, cancel or clear. Legacy /portal set <portal> ..., glow on/off and positional colors remain accepted; use the organized syntax for new setups.
Prefix destination rows with /portal set destination
| Command or setting | Action |
|---|---|
particle-effect <effect/none> |
Arrival particles |
sound <key/none/inherit> [volume] [pitch] |
Arrival audio override |
command add <console:command / player:command> [0/1] |
Destination command; 1 before travel, 0 after arrival |
command remove <index>; command clear |
Remove destination commands |
/portal open <portal> [duration/forever] [players/unlimited] |
Start a new opening window |
/portal close <portal> [duration] |
Close indefinitely or reopen permanently after the delay |
| Node | Default | Purpose |
|---|---|---|
ultraportals.admin |
Operators | All management commands |
ultraportals.use |
Everyone | Portal use |
ultraportals.bypass.cooldown |
False | Cooldown bypass only |
Refunds need no admin permission. Requirements/costs still apply to operators. Setting aliases: destination/destinations, triggerblock/trigger-block, requirement/requirements and cost/costs. The old /up root alias is not registered.
Built-in PlaceholderAPI values for players and portals.
The expansion registers automatically and persists across PlaceholderAPI reloads. Names below use the saved portal ID, including IDs containing underscores.
| Placeholder | Result |
|---|---|
%ultraportals_version% |
1.0.0 |
%ultraportals_portals% |
Number of saved portals |
%ultraportals_destinations% |
Number of saved destinations |
%ultraportals_visits% |
Successful portal trips for the online player |
%ultraportals_cooldown_lobby% |
Remaining cooldown, such as 1m 10s |
%ultraportals_cooldown_seconds_lobby% |
Remaining cooldown rounded up to seconds |
%ultraportals_name_lobby% |
Portal display name |
%ultraportals_enabled_lobby% |
true or false |
%ultraportals_particle_effect_lobby% |
Departure effect ID or none |
%ultraportals_destination_particle_effect_spawn% |
Destination arrival effect ID or none |
%ultraportals_glow_lobby% |
General glow color or off |
%ultraportals_active_glow_lobby% |
Resolved state color or none |
%ultraportals_permanent_particle_effect_lobby% |
Permanent effect ID or none |
%ultraportals_open_mode_lobby% |
true when command-controlled opening mode is enabled |
%ultraportals_open_lobby% |
true when the portal is enabled and its opening state allows entry |
%ultraportals_state_lobby% |
Configurable colored state label: Open, Closed or Disabled |
%ultraportals_open_time_lobby% |
Time until closing/reopening, or the configured permanent label |
%ultraportals_open_seconds_lobby% |
Remaining transition time rounded up to seconds; 0 for permanent states |
%ultraportals_entered_lobby% |
Completed entries in the current/most recent opening |
%ultraportals_players_lobby% |
Alias for the completed-entry count |
%ultraportals_max_players_lobby% |
Maximum entries or the configured unlimited label |
%ultraportals_max_players_raw_lobby% |
Numeric maximum; 0 means unlimited |
Offline visits are deliberately not fetched from disk during placeholder requests; they return 0. Individual cooldowns that have not expired are cached and can be resolved without loading offline players. Unknown placeholder names return no expansion result.
%ultraportals_server_lobby% returns the configured target server or none. Replace lobby/spawn in examples with saved IDs. The expansion registers automatically; no UltraPortals eCloud download is required. External expansions used in conditions must be installed separately.

UltraDungeons is a custom dungeon engine for Paper 1.21.11. Build solo and cooperative adventures with an interactive in-game editor, controlled mob encounters, configurable doors and stored rewards. Shape each run with waiting rooms, combat phases, connecting corridors and boss fights.
Build with contextual hotbar tools and configurable menus. Create reusable templates in a void world so several parties can play independent copies of the same dungeon.
Build an ordered route with shared kill objectives and MythicMobs or EliteMobs encounters. Configure party readiness, start countdowns and separate run and exit timers.
Use passage regions, removable blocks or FAWE schematic states. Add custom glowing outlines that guide each player toward their next exit as they progress.
Store personal item and currency rewards until players leave. Choose manual or automatic delivery, configure death penalties and use supported custom item and economy integrations.
Install the JAR and only the integrations your dungeon needs.
Install the plugins needed by the features you plan to use.
Install each provider required by the features your dungeon uses.
Needed for MythicMobs encounters and native MythicMobs spawners. Custom mobs, skills and native spawner definitions.
Needed for EliteMobs encounters. Custom bosses referenced by their boss filenames.
Needed for instance copies and schematic doors. Copies dungeon blocks and pastes open/closed door schematics.
Needed for ritual regions. Altar encounters and completion objectives. Use a build with dungeon objective callbacks and instance support.
Add these plugins when you want their extra features.
Delegates block protection to managed regions.
Deposits money rewards through an economy provider registered with Vault.
Rewards using configured custom currencies.
Rewards built from ItemsAdder item IDs.
Rewards built from Nexo item IDs.
Rewards built from Oraxen item IDs.
External placeholders from installed expansions. Internal UltraDungeons placeholders work directly.
Portals inside templates receive translated portal bounds, glow geometry and destinations in each instance.
Copies linked loot containers into instances. Not yet publicly available. Requires the build with dungeon instance support.
Copies linked loot tables and container locations into instances, with cleanup of instance links and cooldowns. Compatible container integration targets PhatLoots 5.6.7.
Choose a fixed custom map or a template that creates independent copies for parties.
A custom dungeon uses the map you build in its existing world. One party occupies that map until the run and its cleanup finish.
/dungeon create custom crypt
/dungeon editor crypt/dungeon lobby set crypt. A configured global lobby takes priority.mob-loot.yml. Reward definitions live in loot/./dungeon finish crypt
/dungeon editor exit
/dungeon join crypt
/dungeon start
An instance dungeon is a reusable template. Each party plays in its own copy, allowing several parties to run the same adventure independently. FastAsyncWorldEdit is required.
/dungeon create instance crypt_instance
/dungeon editor crypt_instance/dungeon finish crypt_instance
/dungeon editor exit
/dungeon join crypt_instance
/dungeon startThe dungeon browser lists active copies. Players can join a waiting copy with capacity or create a separate instance. When the last participant leaves, the copy and its runtime integrations are cleaned up. Active templates can keep one reserve copy when capacity permits.
instances:
max-active: 8
max-blocks: 2000000These global limits cap active copies and the copied volume per template. Set max-active to 0 to disable new copies.
Validate the main boundary, external return lobby, consecutive route IDs, provider mobs, ritual objectives and required doors. Every phase or boss needs spawners and valid kill requirements. Each ritual region needs a valid UltraRituals ritual. Test entry, progression, rewards and return travel with a player account.
Configure WorldGuard flags, UltraPortals portals, UltraRituals rituals and linked loot containers on the template. Copies receive their own locations and runtime state. UltraRituals and UltraLootChest need builds with dungeon instance support. PhatLoots container support targets 5.6.7.
Use the hotbar for common actions and full panels for detailed settings.
These are positions 1–9 as seen in-game; YAML uses slots 0–8. Tools stay locked. The free slot accepts blocks for selection markers. Your original inventory is restored on exit.
Editor tools and layouts are built in. Set lang: en or lang: es in config.yml for English or Spanish administration. Leave editing before reloading.
| Item | Action |
|---|---|
| Root category tool | Right: basic hotbar shortcuts. Left: full panel |
| Context Nether Star | Either click: previous hotbar section, back to root |
| All settings | Open the current section's full panel |
| Wand | Left: point 1. Right: point 2. Repeat the same click to correct that corner before completing the other |
| Placement spawner | Block: choose a mob. Air: browse existing spawners |
| Numeric field | Click to enter an exact value |
| Region entry | Left: edit. Right: move one position right. Q: delete |
| Region type | Shift + left in the full region list cycles phase → corridor → boss → ritual |
Dialogs offer Save, Preview, Write in chat and Cancel. Preview renders submitted text and keeps it available for editing. It updates on button press, not per keystroke. In chat input, type cancel to return.
Administration inventories, hotbars and dialogs follow config.yml → lang. Old editor layouts move to data/legacy-editor/. Set dialogs.enabled: false to use chat input. Player-facing menus remain configurable.
Set up waiting rooms, combat phases, corridors and bosses. Arrange them in the order players will follow.
| Type | Default icon | Purpose | Counts as a level? |
|---|---|---|---|
| Waiting | Ender pearl | Gather before starting | No |
| Phase | Iron sword | Mob-kill objectives | Yes |
| Corridor | Stone bricks | Automatically connect encounters | No |
| Ritual | Respawn anchor | Complete linked UltraRituals encounters | Yes |
| Boss | Dragon head | Combat with a configurable BOSS entrance title | Yes |
Ritual regions require UltraRituals. Place all ritual altars and its spawn point inside the region, then validate the dungeon.
Boss type does not create a boss mob automatically: configure its spawners and requirements. Corridors suppress inherited combat announcements; custom titles and commands remain available.
| Walk-in start | Teleport start |
|---|---|
| Define waiting region 0 and waiting spawns | Define player starting points in region 1 |
| Configure the 0:1 entrance | Leave 0:1 unconfigured |
| Players walk through after preparation | Players teleport when combat starts |
A 0:1 entrance takes priority over region-1 spawn points. Waiting has its own panel and no requirements, spawners or completion actions.
Completing the preceding phase opens the corridor entrance and automatically opens its exit too. Consecutive corridors use the normal gate/journal path. A final corridor opens end and starts the completed timer. Switching a room to corridor retains its combat data for switching back, but disables combat behavior. Older mob regions with empty requirements are inferred as corridors. Custom entrance text and explicit commands can still run; built-in combat titles are suppressed.
Advance the dungeon by completing UltraRituals encounters inside a ritual region.
/dungeon level set 2 ritualThe command uses the current wand selection while editing. Replace 2 with the desired route ID.
Ritual regions use their linked ritual objectives in place of mob-kill requirements. The party must complete every linked ritual before progressing. Activation belongs to participants in the current running region. Completing a ritual from another party or an earlier run cannot complete this party’s objective.
Rituals are discovered automatically when integrations synchronize. A ritual crossing the region boundary fails validation. Keep all its points inside the template bounds for instances.
The default entrance title is RITUAL. Region entrance text and presentation can be customized. Create combat spawners in phase or boss regions, and configure the ritual encounter itself through UltraRituals.
Configure provider mobs, per-region reward rolls and shared kill objectives.
Mob definitions and reward rolls are stored in dungeons/<id>/mob-loot.yml. The dungeon layout is saved separately in dungeons/<id>/dungeon.yml. Reward items and currencies remain reusable definitions under loot/.
Each mob entry identifies its provider, provider source ID and assigned region. Spawners in the same region can share an entry. The same provider mob can use different rewards in another region or dungeon. Missing entries are added when saving or reloading assigned spawners. Generated IDs use the source name and a numeric suffix.
SkeletalKnight_0:
provider: MYTHICMOBS
source-id: SkeletalKnight
level: 1
loot:
- id: dungeon_sword
chance: 15.0
min: 1
max: 1
- id: gold_coins
chance: 100.0
min: 5
max: 10
dungeon_guard_0:
provider: ELITEMOBS
source-id: dungeon_guard.yml
level: 3
loot: []The top-level key is the UltraDungeons mob ID. source-id is the real MythicMobs ID or EliteMobs custom boss filename. level is the ordered region ID. Create those mobs in the provider and define the referenced reward IDs in loot/.
loot/editor.yml.Saving updates this dungeon’s mob-loot file. Spawners sharing that region’s mob entry share its reward settings.
Each newly assigned mob starts at one required kill, shared by the party. Only tracked mobs killed by participants in the active room contribute. Set a requirement to 0 for an ambient mob. A room whose requirements are all 0 advances when participants arrive. Removing a spawner removes a mob requirement only when no remaining spawner supplies that mob.
Use UltraDungeons spawn points or native MythicMobs spawners inside phase and boss regions.
| Setting | Default | Meaning |
|---|---|---|
| Amount | 1 | Mobs per cycle. |
| Cooldown | 15 seconds | Delay between spawn cycles. |
| Maximum alive | 2 | Living population cap. |
| Activation range | 64 blocks | Use -1 for activation while participants are in the room. |
| Radius | 2 blocks | Spawn spread around the saved point. |
Apply settings to all copies numerical settings to custom spawners without changing their mobs or positions.
Create and configure native spawners in MythicMobs inside a dungeon’s phase or boss regions. UltraDungeons discovers them automatically, alongside its custom spawners. Source positions, mob types and native options stay in MythicMobs.
Sources synchronize every five seconds while the dungeon is idle and during validation. Mob-loot entries and kill requirements belong to the dungeon and region. Replacing a source mob keeps its previous rewards and kill count unless the replacement already has settings.
Each run uses temporary native spawner copies with its own mob population. Instance positions are translated into that party’s copy. Edit or remove a native source in MythicMobs. Waiting rooms, corridors and ritual regions are excluded.
Click the spawner tool in air to open the directory. Open a custom spawner’s settings from its entry or right-click its temporary editor block. Use Q on a directory entry, Delete in its settings, or break its temporary block to remove a custom definition.
Custom definitions appear as real temporary spawner blocks in loaded chunks within 48 blocks, up to 96 per editor. These previews never generate mobs. They restore the original blocks when editing ends and are removed during instance copying. The recovery journal restores interrupted previews after startup or world load. Existing block entities and native MythicMobs spawners are preserved.
Set up door connections, schematic states and per-player glow.
Groups are generated automatically. Add multiple accesses such as 1:2 and 1:2@2; they unlock together. Use the Doors shortcut to browse groups and add accesses.
| Method | Configure | Result |
|---|---|---|
| Passage only | Door corner selection | Movement allowed; blocks unchanged |
| Remove materials | Corners + Blocks to remove | Matching blocks become air |
| Schematic | Closed/open files and paste origins | FAWE pastes the chosen state |
Click the selection item, then use the wand for both corners. An opening schematic takes priority over block removal. Remove both schematic states to return to a plain region.
Press Q over an access entry to delete that door and its states/glow. Other accesses remain. The generated connection group stays available for rebuilding. The directory's red/green Optional doors toggle permits missing doors when enabled. Configured doors still validate; external openings do not bypass kill objectives. Without end, set a nonzero completed timeout or use /dungeon leave.
YAML example
# In dungeons/<id>/dungeon.yml
doors:
optional: trueMerge this fragment into the existing file; keep its other settings.
A door's Blocks to remove button opens a multi-selection panel. Click block items in your own temporary inventory to toggle their material, click a selected entry to remove it, or use the block catalog. Selection never consumes or transfers the clicked stack. Several block types can be enabled for the same door:
YAML example
gate-blocks:
'1:2': [OAK_FENCE, IRON_BARS]
'1:2@2': [SPRUCE_FENCE]Merge this fragment into the existing file; keep its other settings.
Only matching block types inside that access door's boundary become air when its progression group opens. All other blocks remain unchanged. An opening schematic takes priority over block removal. An empty selection keeps the original passage-only behavior. Original block states are committed to the gate recovery journal before modification and restored when the party leaves, during recovery or on shutdown. Work respects the configured gate size and per-tick block budget. Block entities and containers remain unsupported in mutable gate regions. Reordering rooms carries their incoming doors' removable-block settings; deleting a door removes its settings too.
FastAsyncWorldEdit is required for schematic doors. The editor lists local files and available FAWE schematic files. Selecting a file configures and pastes that state at the player's current position. Closed and open states can have different origins. The ignore-air option corresponds to WorldEdit's -a behavior.
Command example
/dungeon gate schematic 1:2 closed doors/closed.schem -a
/dungeon gate schematic 1:2 open doors/open.schemBoth states must be configured before activation. Clipboard loading, validation and paste/flush work use a dedicated worker. Closed schematics establish the baseline on activation and before admission. Original block data covering both state footprints is committed to SQLite before opening. Reset restores that baseline. Schematic footprints of different doors may not overlap; bounds must satisfy configured block limits and world height. Block entities are rejected to preserve complete recovery. Schematic entities and biomes are not pasted. Reconfigure a state after changing its schematic dimensions.
Important: if an open schematic needs air to clear the door, do not enable ignore-air for that state.
Global pushback applies to approaching participants on either side of a closed door, including movement within one block. It stops when the group opens. Teleports are validated separately and do not receive movement knockback.
YAML example
gates:
pushback:
enabled: true
strength: 0.65
vertical-strength: 0.12
distance: 0.6
cooldown-ticks: 8Merge this fragment into the existing file; keep its other settings.
Horizontal/vertical strength are velocity components; distance is the horizontal approach margin in blocks. Cooldown limits repeated velocity updates, the configured gates.pushback.sound and the gate-pushback message while closed-door passage remains blocked. Set the sound or message to an empty string to mute it. Disabling pushback keeps ordinary region passage restrictions.
Outline any door shape and guide each player according to their own progress.
The first shape is also applied to the other state. Edit the other state explicitly for a different shape. Irregular outlines, holes and disconnected selections are supported.
Crossing hides the previous door for that player. Teammates still approaching keep their guidance. Revisiting earlier rooms does not restore crossed outlines. Previews are private to the editor.
Selections support up to 4096 blocks (also limited by max-gate-blocks) and 1024 contour segments. Volumetric shapes retain exterior creases. The first state's geometry follows into the other until that state is explicitly edited. Saved selection-defined markers preserve this relationship.
YAML example
gate-glow:
'1:2':
closed:
enabled: true
blocks:
- {world: world, x: 20, y: 65, z: 12}
- {world: world, x: 20, y: 66, z: 12}
open:
enabled: trueMerge this fragment into the existing file; keep its other settings.
This fragment belongs to the dungeon file. Reset uses the boundary again. Without explicit shape data, the closed state uses the door boundary and an open schematic can supply open bounds. Legacy rectangular region settings remain readable.
Control where the party gathers, when combat starts and what happens when time expires.
Join with /dungeon join <id> or /dungeon play <id>. Each participant confirms with /dungeon start. Unready players are removed after the readiness window and the ready party continues. A fixed map stays occupied until its party leaves and the gates restore. Instance templates can serve other parties in separate cells while a copy is playing or being cleaned up.
| Destination | Priority |
|---|---|
| Waiting | Waiting-room spawns → local lobby → global lobby fallback |
| Combat start | Open configured 0:1; otherwise teleport to region-1 starting points |
| Return | Global lobby if configured; otherwise local lobby |
Set the global return point outside editing with /dungeon globallobby set; remove it with /dungeon globallobby unset. The local lobby still serves as its waiting location.
| Timer | Default | Purpose |
|---|---|---|
| Readiness | 30 seconds | Teammates confirm |
| Preparation | 5 seconds | Final countdown |
| Dungeon | 5 minutes | Complete the route |
| Completed | 30 seconds | Leave after final completion |
Completion messages and the completed scoreboard appear when the last objective completes, before crossing end. Completed expiry returns remaining players without a loot penalty. Set dungeon/completed limits to 0 to disable each independently.
The scoreboard refreshes at the same displayed second as the preparation title, even with a longer configured scoreboard interval. Countdown sounds play once for each displayed number and are separate from the epic start sound.
YAML example
start:
countdown:
enabled: true
seconds: 5
sounds:
- sound: BLOCK_NOTE_BLOCK_PLING
volume: 0.65
pitch: 1.1Merge this fragment into the existing file; keep its other settings.
Configure this in config.yml or override start.countdown.sounds inside a dungeon. An empty list [] mutes only the countdown. start.sounds still controls the actual start sound.
Hotbar ender-pearl icons retain the pearl appearance using an inert menu item model, avoiding vanilla throwing and cooldown animation. Real inventory items are unchanged.
The default final countdown is 5 seconds, separate from the 30-second readiness confirmation window. During COUNTDOWN, admission stays locked, players remain in the waiting area, entrance doors stay closed and spawners do not activate. Each remaining second is sent once through start-countdown in messages.yml, which defaults to a title/subtitle. The shared HUD timer drives this independently of the spawner update interval.
YAML example
start:
ready-timeout-seconds: 30
countdown:
enabled: true
seconds: 5
sounds:
- sound: ENTITY_ENDER_DRAGON_GROWL
volume: 0.6
pitch: 0.8Merge this fragment into the existing file; keep its other settings.
Override start.countdown.enabled, start.countdown.seconds and/or start.sounds inside an individual dungeon file; omitted keys inherit global values. A disabled countdown or zero seconds starts immediately after readiness. sounds: [] mutes the start sound. Configured sounds play once for each retained participant after the entrance has opened or the start teleport succeeds. Leaving the final countdown with no participants cancels the pending start. Sound keys accept Minecraft names or namespaced keys; volume and pitch use the same bounds as completion sounds. The countdown supports 0-300 seconds. Readiness timeout remains global.
Global defaults and per-dungeon overrides use the same keys:
YAML example
time-limits:
dungeon-seconds: 300
completed-seconds: 30
timeout-action: RETURN_PERCENT
waiting-room:
actionbar:
enabled: trueMerge this fragment into the existing file; keep its other settings.
Combat time begins after preparation finishes and the entrance opens. Completing the last level immediately sends completed and switches the sidebar and countdown, even if FAWE is still pasting the exit. The exit timer automatically returns remaining players to the main lobby with all current-run loot; crossing end also returns without penalty. The completed deadline belongs to the party. Set either limit to 0 to disable it independently. Run limits are captured when combat starts.
| Global timeout policy | Result | Current-run loot loss |
|---|---|---|
KILL_PERCENT | Real death, then return at respawn | Configured death-loss percentage |
KILL_ALL | Real death, then return at respawn | 100% |
RETURN_PERCENT | Return directly to the main lobby | Configured death-loss percentage |
RETURN_ALL | Return directly to the main lobby | 100% |
Previously stored loot is preserved. Killing policies use normal Minecraft death behavior for the player's existing inventory. Loot loss applies to this plugin's current-run rewards. Automatic delivery waits until the player is alive.
Define reusable rewards, assign them to mobs and choose how players collect them.
Rolls are stored in dungeons/<id>/mob-loot.yml. Spawners sharing the same mob entry in that region share these settings. Other regions and dungeons can configure their own rewards. A new roll starts at 100% with a multiplier of 1. A multiplier of 2 gives two copies of the saved stack or doubles the base currency amount. You can import items with /dungeon import before entering editor mode and then select them in the catalog.
The collection menu supports unlimited pages and compacts remaining entries when reopened. Players can withdraw rewards, never insert items. Claiming is blocked while joining, waiting or playing.
| Under loot: | Behavior |
|---|---|
| delivery: MENU | Manual collection |
| delivery: INVENTORY | Automatic delivery; overflow/failed deposits remain stored |
| require-empty-before-join: true | Clear stored/reserved loot before another entry |
| death-loss-percent: 20.0 | Retain 80% of the current run's rewards |
| distribution: EACH | Personal rolls for living participants in the room |
| distribution: KILLER | Reward only the killer |
Configure globally or override individual keys per dungeon. Previous unlocked rewards are untouched by death. Ordinary leaving, logout and completion unlock earned loot without a death penalty. Retained item units round down; money scales proportionally.
Hold the original item and run:
Command example
/dungeon import royal_sword weapons/swordsWrites to loot/weapons/swords.yml. Without a file argument, it uses loot/imported/royal_sword.yml. Serialized data preserves item components and plugin metadata; existing IDs are rejected.
YAML example
# Multiple loot definitions per file; files may be nested in subdirectories.
dungeon_sword:
type: ITEM
material: DIAMOND_SWORD
amount: 1
name: '&6Dungeon sword'
lore: ['&7A prize from the depths.']
enchantments:
sharpness: 3
unbreaking: 2
unbreakable: false
flags: [HIDE_ATTRIBUTES]
attributes:
- attribute: attack_damage
amount: 2.0
operation: ADD_NUMBER
slot: HAND
# Money is stored as a reward, never dropped on the ground.
gold_coins:
type: MONEY
provider: VAULT # EXCELLENTECONOMY uses currency below.
currency: coins
amount: 1.0
# Optional custom items: type: ITEM, provider: ITEMSADDER|NEXO|ORAXEN, id: namespace:item.
# /dungeon import captures full item NBT into a serialized field, preserving all components.Merge this fragment into the existing file; keep its other settings.
YAML example
ancient_key:
type: ITEM
provider: ITEMSADDER
id: 'dungeons:ancient_key'Merge this fragment into the existing file; keep its other settings.
Use NEXO or ORAXEN in the same provider field for those integrations. Import an existing item when preserving all original item data is essential; avoid overriding imported serialized metadata.
Money definitions use type: MONEY, provider: EXCELLENTECONOMY, amount and the currency ID. Files support subfolders and multiple reward IDs. UltraDungeons owns stored rewards for its tracked mobs. Avoid provider drops or independent reward-generating skills/commands. Ordinary tracked drops/XP are suppressed, but external skills can still create separate items.
Open a combat room’s More Options panel to configure event actions and presentation.
| When | Settings |
|---|---|
| First successful room entry | Entrance title, subtitle, start commands and sounds |
| While inside | Persistent action-bar text |
| Room completed | Completion commands, sounds and firework preset |
Entrance titles run once per player per room, not on revisits. Boss rooms have a BOSS preset; corridors suppress the inherited combat title. Custom corridor titles still work.
Commands have no leading slash. EACH_PLAYER executes for each participant; ONCE executes once, using the first entrant for start and the final killer context for completion.
Omitted lists inherit. An empty list mutes. The sound editor accepts SOUND [volume] [pitch], with inherit/mute controls.
Choose a preset in the effects panel: celebration, emerald or inferno. Add your own YAML files under completion-effects/ (subfolders supported), then reload.
Commands now live together under commands.on-start and commands.on-complete. Each event has mode (EACH_PLAYER or ONCE) and list. Sounds live under sounds.on-start / sounds.on-complete; entry titles live under titles.on-enter.
YAML example
levels:
'1':
type: phase
titles:
on-enter:
title: '&6The crypt'
subtitle: ''
fade-in: 10
stay: 60
fade-out: 10
commands:
on-start:
mode: EACH_PLAYER
list: ['say {player} entered {level}']
on-complete:
mode: ONCE
list: ['say Level {level} completed']
sounds:
on-complete:
- sound: ENTITY_PLAYER_LEVELUP
volume: 0.8
pitch: 1.2Merge this fragment into the existing file; keep its other settings.
The old on-start, on-complete and on-enter sections remain readable. Saving through the editor rewrites them into these groups. Modern values take priority when both formats define the same setting. Corridor commands still run; only the automatic combat announcement and inherited combat sounds are suppressed.
YAML example
levels:
'1':
actionbar:
enabled: true
text: '&eLevel {level} &8| &f{remaining} mobs left'
completion-effect: celebration
commands:
on-start:
mode: EACH_PLAYER
list:
- say {player} entered level {level}
sounds:
on-start:
- sound: BLOCK_NOTE_BLOCK_PLING
volume: 0.5
pitch: 1.2Merge this fragment into the existing file; keep its other settings.
YAML example
name: '&6Golden celebration'
amount: 3
interval-ticks: 5
explosion-ticks: 20
power: 1
type: BALL_LARGE
trail: true
flicker: true
colors: ['#FFCC33', '#FFFFFF']
fade-colors: ['#FFFFFF']Merge this fragment into the existing file; keep its other settings.
Choose the effect ID in the room; each effect file defines one preset. Rocket types: BALL, BALL_LARGE, STAR, BURST, CREEPER. Amount 1–32; interval/fuse 1–200 ticks; power 0–3; up to 16 colors per list. Explosion ticks control fuse, not the particle lifetime. Rockets launch at participants without damage and stop launching after departure.
Configure scoreboards, boss bars and action bars for each stage of a run.
Edit scoreboards.yml under default. Add a section named after a dungeon ID to override each state. Layouts support title, up to 15 lines and update-interval in ticks. Red numbers are hidden; the previous scoreboard returns on departure.
| Display | Configure |
|---|---|
| Combat boss bar | config.yml → bossbar; per-dungeon overrides supported |
| Waiting action bar | waiting-room.actionbar.enabled; messages.yml → waiting-actionbar |
| Room persistent action bar | More Options, or levels.<id>.actionbar |
| Next-door / exit guidance | messages.yml → next-level-actionbar / exit-actionbar |
| Editor status | Built-in editor resources, following config.yml → lang |
Next-door guidance overrides permanent room text until that player enters the next region. It stays dismissed on revisits. Persistent HUD templates are scalar strings; an empty string hides them.
YAML example
# A dungeon ID overrides default. Intervals are server ticks (20 ticks = one second).
# Up to 15 lines; duplicate and blank lines are supported. Score numbers are hidden.
# All text supports legacy colors, &#RRGGBB, MiniMessage and PlaceholderAPI.
# Internal placeholders: player, dungeon, dungeon_id, level, levels, players,
# max_players, ready, kills, required, remaining, state, seconds,
# time_left (m:ss), dungeon_seconds, exit_seconds, kills_<mob-id> and required_<mob-id>. Surround internal placeholders with { }.
default:
# Waiting and readiness use their own board, with no combat counters.
# Add the same waiting section under a dungeon ID to override it for that dungeon.
waiting:
update-interval: 20
title: '&#ffb347&lUltraDungeons'
lines:
- '&8&m----------------------'
- '&7Dungeon: &f{dungeon}'
- '&7Status: ee8fa{state}'
- ''
- '&7Players: &f{players}&7/&f{max_players}'
- '&7Ready: &f{ready}&7/&f{players}'
- '&7Time left: &e{seconds}s'
- ''
- '&eUse /dungeon start'
- '&8&m----------------------'
# Combat board.
started:
update-interval: 20
title: '&#ffb347&lUltraDungeons'
lines:
- '&8&m----------------------'
- '&7Dungeon: &f{dungeon}'
- '&7Status: ee8fa{state}'
- ''
- '&7Level: &e{level}&7/&e{levels}'
- '&7Mobs: &a{kills}&7/&a{required}'
- '&7Time left: &e{time_left}'
- '&7Players: &f{players}&7/&f{max_players}'
- '&8&m----------------------'
# Displayed after the final level unlocks end, until each player leaves.
completed:
update-interval: 20
title: 'Pff80&lDungeon completed'
lines:
- '&8&m----------------------'
- '&7Dungeon: &f{dungeon}'
- '&7Players: &f{players}&7/&f{max_players}'
- ''
- '&aAll levels completed!'
- '&eGo to the exit portal.'
- '&7Time to leave: &e{time_left}'
- '&8&m----------------------'Merge this fragment into the existing file; keep its other settings.
Customize chat, titles and action bar messages with colors and placeholders.
| Format | Example |
|---|---|
| Legacy colors & styles | &aGreen &lBold |
| HEX | 7AAFFBlue |
| MiniMessage | <#55aaff>Blue or <gradient:gold:yellow>Text</gradient> |
| Internal placeholders | {dungeon}, {player}, {level}, where context supports them |
| PlaceholderAPI | Installed expansion placeholders, such as %player_name% |
YAML example
spawner-item: '&aPlace this item inside a combat room.'
level-complete:
chat: '&aLevel {level} complete!'
title: '&6Level complete'
subtitle: '&eContinue to the next room'
actionbar: '&7Exit unlocked'Merge this fragment into the existing file; keep its other settings.
Use a scalar for chat only. Omit unused channels. An empty scalar disables a message. Chat can also be a list. Optional fade-in, stay and fade-out use ticks (defaults 10/60/10). Per-action save confirmations live under editor-saved and follow a successful file write.
Customize the dungeon browser, loot menu and editor panels.
Use guis/loot.yml for stored rewards, guis/dungeons.yml for the dungeon browser and guis/instances.yml for active copies. Editor panels use built-in English or Spanish resources selected by config.yml → lang.
Use material: PLAYER_HEAD with value: self for the viewer's head, or a Base64 texture value for a custom head. Names, lore, materials and supported metadata are configurable. PlaceholderAPI works in supported panel text. Bundled panels use six rows. Player-facing inventory layouts are configured in their menu files. Content slots and navigation are configurable. Previous/next controls only appear if another page exists. YAML slots are zero-based.
See Editor for hotbar shortcuts and dialog settings.
In guis/loot.yml, edit the existing items.close entry. This example keeps the close action and uses a Base64 texture for its icon. YAML slots start at 0.
# In guis/loot.yml, replace the existing close item.
items:
close:
material: PLAYER_HEAD
value: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZGE1ZDgwNTY3MDY4MmY0Njg4MDFiZmI2YWRkNGY0ZmY1ODhiOWI2OTllMGVmNzJiNjQ5OGYxNWJmMjlmOWZkMyJ9fX0="
name: '&cClose'
lore:
- '&7Click to close the menu.'
slots:
- 49
action: CLOSEReplace value with the Base64 texture of your chosen head. The decoded texture must point to textures.minecraft.net. Use value: self to show the viewing player’s head.
Delegate block rules while UltraDungeons keeps control of encounters and progression.
| Setting / availability | Behavior |
|---|---|
| worldguard: false | Built-in protection |
| worldguard: true + successful sync | Managed WorldGuard cuboid at the main bounds |
| WorldGuard absent or sync failure | Built-in protection remains active |
New dungeon defaults follow installed WorldGuard availability; existing explicit choices are preserved.
The internal WorldGuard string flag ultradungeons-owner marks the dungeon ID. Do not edit that marker or rename the managed region. Foreign regions without the marker are never overwritten/deleted. Bounds updates preserve flags, priority, owners, members and parent relationships. Child regions are reattached on bounds replacement; deleting the managed parent unsets their parent without deleting the child regions.
Use /dungeon delete <id> outside editor mode after the dungeon is empty, or remove its YAML file and reload. Managed regions are cleaned up in loaded worlds. An unloaded world's cleanup runs when that world loads. WorldGuard must be available for its saved region data to be modified.
Set worldguard: false and reload to remove the managed region and restore internal protection. WorldGuard must be available for cleanup. Doors outside the main bounds retain internal block protection.
A cuboid stores coordinates and metadata; creating it does not copy or scan its blocks. Synchronization runs at configuration/lifecycle events, not every tick, and unchanged bounds are cached. WorldGuard handles indexing and automatic persistence. Reload/cleanup cost grows with the number of loaded regions rather than the dungeon's block volume.
Instance regions copy the template's current flags, priority and ownership before admitting players. Each copy uses its own region ID. Copying and clearing the blocks is the larger operation and runs through FAWE.
Use /dungeon or its alias /dungeons.
| Command | Action |
|---|---|
/dungeon [menu] | Open the dungeon browser. |
/dungeon help | Show the commands available to you. |
/dungeon join <id> | Join a published dungeon. |
/dungeon play <id> | Join a published dungeon. Alias of join. |
/dungeon start | Confirm that you are ready. |
/dungeon leave | Leave the dungeon and unlock earned rewards. |
/dungeon loot | Open the stored rewards menu. |
| Command | Action |
|---|---|
/dungeon create <custom|instance> <id> | Create an inactive dungeon or instance template. |
/dungeon editor [id] | Edit the specified dungeon or reopen the editor panel for your current dungeon. |
/dungeon editor exit | Leave the editor. |
/dungeon wand | Get the region selection wand. |
/dungeon finish <id> | Validate and activate the dungeon. |
/dungeon delete <id> | Delete an unoccupied dungeon that is not being edited and remove its managed region. |
/dungeon lobby <set|unset> [id] | Set or remove the dungeon’s return point. Omit the ID while editing that dungeon. |
/dungeon globallobby <set|unset> | Set or remove the server-wide return point. |
/dungeon import <id> [folder/file] | Import the held item into the loot catalog. |
/dungeon reload | Reload once runs, editors, claims and storage operations are idle. |
Open the editor for the dungeon before running these commands.
| Command | Action |
|---|---|
/dungeon level set 0 | Save the selection as the waiting region. |
/dungeon level set <number> <phase|corridor|boss|ritual> | Set the region and type for a level above 0. |
/dungeon level unset <number> | Remove a level and its related door connections. |
/dungeon maxplayers <count> | Set the player limit. |
/dungeon spawn <set|unset> <index> [0|1] | Set or remove a player spawn. The current room supplies the level when the argument is omitted. |
/dungeon spawner set <name> <mob1,mob2,...> | Place or update a spawner with the specified mob IDs. |
/dungeon spawner configure <name> <option> <value> | Set radius, amount, cooldown (seconds), max-alive or activation-range. |
/dungeon spawner unset <name> | Remove a spawner. |
/dungeon spawners list | List spawners and their coordinates. |
/dungeon spawners locate <name> | Show one spawner’s coordinates. |
/dungeon spawners teleport <name> | Teleport to a spawner. |
/dungeon require add mob <level> <mob> <count> | Set how many of the specified mob must be defeated. |
/dungeon require remove mob <level> <mob> | Remove that mob requirement from the level. |
/dungeon gate <id> | Save the selected region as a door boundary. Examples of IDs include 0:1, 1:2 and end. |
/dungeon gate create <id> | Create an entry for a schematic door. |
/dungeon gate unset <id> | Remove a door and its settings. |
/dungeon gate schematic <id> <closed|open> <file> [-a] | Assign a schematic to one door state. Use -a to skip air blocks. |
| Command | Action |
|---|---|
/dungeon recovery list | List interrupted reward claims. |
/dungeon recovery release <id> | Make the reward claimable again after verifying it was never delivered. |
/dungeon recovery confirm <id> | Clear the claim after verifying the player already received the reward. |
Use internal tokens in supported text fields and PlaceholderAPI expansions for external values.
| Placeholder | Meaning |
|---|---|
{dungeon} / {dungeon_id} | Display name / saved template or custom dungeon ID. |
{level} / {levels} | Current non-corridor progression level / total. Waiting and preparation report level 0. |
{region} / {regions} | Ordered route ID / total positive route regions, including corridors. |
{region_type} | Current room type, such as phase, corridor, ritual or boss. |
{players} / {max_players} / {ready} | Party size / player limit / ready participants. |
{kills} / {required} / {remaining} | Completed / required / remaining objectives. Ritual rooms count ritual completions. |
{kills_<mob-id>} / {required_<mob-id>} | Counters for one assigned mob ID. |
{time_left} / {seconds} | Active phase countdown formatted as m:ss / seconds. |
{dungeon_seconds} / {exit_seconds} | Run / completed exit time remaining. Disabled timers report 0. |
{player} / {state} | Player name / localized run state. |
{next_level} | Next progression level in transition boss bar text. |
| Placeholder | Meaning |
|---|---|
{instance} | Instance number in the browser. |
{status} / {join_status} | Run state / admission availability. |
{player_list} | Expands to one configured player-line per participant. |
{player_name} | Participant name inside player-line. |
Configure the instance browser in guis/instances.yml.
Install PlaceholderAPI and the expansions needed by your text, such as the player expansion for %player_name%. Supported player-facing text can combine external placeholders, legacy colors, HEX and MiniMessage.
Grant access to player features or dungeon administration.
| Permission | Default | Access |
|---|---|---|
ultradungeons.use | Everyone | Dungeon browser, help, join/play, ready confirmation, leaving and stored loot collection. |
ultradungeons.admin | Operators | Editor, dungeon creation/deletion, regions, spawners, doors, requirements, lobbies, reward import, validation, reload and recovery. |
Grant both nodes to administrators who also need player features. Both command aliases use these same permissions.