Warps
Let players publish their protection as a public warp that anybody can visit and rate, and set the teleport countdown.
With submodules.warps, a protection can be published as a public warp: a place anybody may visit from a
list or by name, and rate from one to five stars. A protection has at most one warp. Warps are off by
default.
Before you start#
You need a protection, see Creating protections. Warps are off by default: set submodules.warps: true in config.yml.
Publishing a warp#
Open the warp screen
On the protection's screen click Extras, then Public warp. It needs the role permission manage-warp, which no default role has, so only the owner manages the warp until a role is given it.
Publish it
Click Publish. The protection needs a home.
Dress it up
Click Rename, Icon and Description, and Land here while standing where visitors should arrive.
| Button | What it does |
|---|---|
| Publish | Publishes the warp, or takes it down. Publishing needs the protection to have a home |
| Land here | Moves where visitors land to where you stand, inside the protection, on its server and world |
| Rename | Types the warp's name |
| Icon | Chooses the item the warp shows in the list |
| Description | Types a line shown under the warp in the list |
Moving where visitors land, renaming it, changing its icon or its description while the warp is not published asks whether to publish it first, on the protection's home, and then goes on.
A new warp lands on the protection's home, is named after the protection and shows default-icon. Names and
descriptions are stored as plain text: colour codes and tags are stripped, and anything past
name-max-length or description-max-length is cut. A name does not have to be unique.
Taking a warp down, or deleting its protection, deletes its visits and ratings with it. Every change is written to the protection's log.
Moving the protection's core moves the warp to the protection's new home, since the old spot may now be outside the land or inside somebody else's. Setting a new home with Set home does not move the warp; press Land here for that.
Check that it works#
Run /protections warps, or click Public warps in /protections. Your warp is in the list; left-click it to visit. With warps.hide-unavailable on (default) a warp a player cannot enter now is not listed.
The warps list#
/protections warps, or Public warps in /protections, lists the warps of every server.
| Click | What it does |
|---|---|
| Left-click a warp | Visits it |
| Right-click a warp | Rates it, one to five stars. Your current rating is offered first |
| Sort | Cycles Most visited → Best rated → Newest |
Each row shows the warp's name and stars, its description, the owner, the protection, its server and world, the visits, the average rating and how many players rated it. Ties in visits or rating go to the newest; a tie in the average goes to the warp with more ratings first.
With hide-unavailable on, warps a player cannot enter right now are left out of their list: the protection is
locked or they are banned from it, or it is raidable or abandoned. With it off they are listed, and the visit is
refused.
Visiting#
A visit from the list, or /protections warp <name>, teleports the player to the warp's spot after the
teleport countdown, teleport.warp-warmup-seconds, on whichever server the protection
is. Names are matched ignoring case;
when several warps share one, the most visited wins. The command completes the names of the warps the player's
list shows.
Members of the protection may always visit its warp. Anybody else only while they could walk in: not while it is locked to them, they are banned, or it is raidable or abandoned.
Teleport countdown#
Every teleport the plugin makes runs the same countdown: home (from the list, the overview or
/protections home), visiting a warp, visiting a protection for sale or a rent offer, and an admin's
Teleport. Each goes to whichever server the land is on.
- While it counts, a boss bar shows
TELEPORTING » <name> • <time>and clears however it ends, and a tick sound plays each whole second. On arrival a title with the protection's name, a sound and particles play, then "Welcome to <name>." - Stepping off the starting block, or taking damage, calls it off with "Teleport cancelled » you moved." or
"… you took damage.", when
cancel-on-moveandcancel-on-damageare on. - A player already counting down is told "You are already on your way somewhere."; a player tagged in combat
cannot start one while
refuse-in-combatis on. - With
cooldown-secondsabove 0, a player waits that long between two teleports ("You can teleport again in …"). One that was called off does not count. - Holders of
bypass-permission(exyliaprotections.bypass.warmup, operators by default) move at once and skip the cooldown. They are still refused in combat.
Teleport settings
| Key | Default | What it does |
|---|---|---|
teleport.warmup-seconds | 3 | Seconds before moving home, to a protection for sale or rent, or as an admin. 0 moves at once |
teleport.warp-warmup-seconds | -1 | Seconds before visiting a warp. -1 uses warmup-seconds |
teleport.cancel-on-move | true | Whether stepping off the starting block calls it off |
teleport.cancel-on-damage | true | Whether taking damage calls it off |
teleport.refuse-in-combat | true | Whether a player tagged in combat cannot start one |
teleport.cooldown-seconds | 0 | Seconds between two teleports. 0: none |
teleport.bypass-permission | exyliaprotections.bypass.warmup | Holders move at once and skip the cooldown. Blank for nobody |
teleport.tick-sound | UI_BUTTON_CLICK|0.6|1.3 | Played each whole second: NAME|volume|pitch. Blank for none |
teleport replaced settings.home-warmup-seconds: updating moves that value to teleport.warmup-seconds.
What the countdown shows, the arrival and the four messages are the teleport section of the messages file.
Staff change these keys in game from the admin hub's Teleport settings; see
Administration.
Counting visits#
A visit counts once per player per day, after the teleport arrives, whichever server they
arrive from. Members' visits never count, and neither does a refused one. The day is the calendar day in UTC.
Each new visit adds one to the warp's running total, which every server adds to at once without overwriting
each other. With the survival core installed, each counted visit also counts protections.warp_visits for the
visitor.
The total keeps every visit ever. The per-day records that stop a second count are only needed until the day ends: every six hours, records older than yesterday are deleted. A warp published before the running total existed gets its total counted once from its records, on the first start after updating.
Ratings#
Anybody but the owner rates a warp, members included, with one to five stars from the list. A player has one rating per warp; rating again replaces it. Only a player who visited the warp today or yesterday may rate it; anybody else is told to visit it first.
The average is shown with one decimal, and the stars rounded to the nearest whole one, so an average of 4.5 shows five filled stars.
Placeholders#
These read the warp of the protection the player stands in, and are blank when it has none.
| Placeholder | What it returns |
|---|---|
%exyliaprotections_protections_warp_rating% | Its average rating, with one decimal |
%exyliaprotections_protections_warp_visits% | Its total visits |
Keys#
Warp settings in config.yml
| Key | Default | What it does |
|---|---|---|
submodules.warps | false | Turns warps on |
warps.name-max-length | 24 | The longest name a warp may have |
warps.description-max-length | 64 | The longest description a warp may have |
warps.hide-unavailable | true | Whether warps a player cannot enter right now are hidden from their list. Off: listed, and the visit refused |
warps.default-icon | LODESTONE | The icon a new warp starts with |
submodules:
warps: false
warps:
name-max-length: 24
description-max-length: 64
hide-unavailable: true
default-icon: LODESTONETurning warps off hides the list, the command and the warp screen, and keeps every warp, visit and rating for
when they are turned back on. Warps are stored in protections_warps, ratings in protections_warp_ratings,
the per-day visit records in protections_warp_visits and the running totals in protections_warp_totals.
Something missing on this page? Tell us on Discord