atriusx/waystones

A small plugin that brings long-distance teleportation to Minecraft survival mode!

Waystones

Waystones is a minecraft server plugin that brings teleportation to your worlds without needing to rely on commands. This plugin works great in survival worlds where command teleporting is often out of place or just overpowered in general.

How to use it:

Players can create and warp to a waystone by creating a lodestone and linking it with a compass or warp key (more on this later). When the player right-clicks the warp key, they will initiate a teleport to the linked waystone.

Other Features:

• When single use warp keys is enabled, warp keys will be destroyed upon warping.
• When distance limiting is enabled, users can place blocks around the warp stone to increase its max range!
  • Supported blocks include Netherite (max boost), Emerald (75% boost), Diamond (50% boost), Gold (33% boost) or Iron (20% boost) blocks.
  • Obsidian can be placed under a lodestone to prevent it from being used as a waystone!
  • For admins, a command block can be placed under a lodestone to remove the range limit and power requirements!
• When power requirements are enabled, users can place a respawn anchor under the waystone to allow for teleportation!
  • This can be set for all warps or just ones between dimensions!
  • The waystone will work as long as the respawn anchor remains charged.
  • Respawn anchors can be auto-recharged upon warping!
  • A ratio can be applied to the warp range to divide the max range of interdimensional warps.
• Waystones can be named using a name tag!
• When portal sickness is enabled, players have a random chance of being hit with this effect upon teleporting!
  • Grants Nausea X for 30 seconds and Blindness for 5 seconds.
  • If sick warping is set, then players can be blocked from warping until they recover, or take damage from subsequent warps if they are sick!
• A crafting recipe for warp keys can be enabled.
  • This allows compasses to function as normal, and creates a custom item to use as the warp key!

Crafting a Warp Key:

The default crafting recipe for the warp key is as follows:

Please note that this recipe is only used if enable-key-items is set to true in the configuration file. In future updates this recipe may also potentially be customizable via the config.

Configuration Options:

• locale [default: en]: The localization file to be used (named lang-locale.yml). This will also affect how numbers or date are formatted if the locale matches any BCP 47 language tag, or the language/country neutral format will be used.
• wait-time [default: 60]: The amount of time (in ticks) to wait before teleporting to the waystone. Moving will cancel the teleport.
• damage-stops-warping [default: true]: Whether taking damage will prevent the player from teleporting.
• limit-distance [default: true]: Limits the range of a waystone to the base distance plus the total boost value.
• base-distance [default: 100]: The minimum amount of blocks in range a waystone will have.
• max-boost [default: 150]: The max boost amount permitted per block of a waystone.
• max-warp-size [default: 50]: The max number of boost blocks a warp is able to use.
• jump-worlds [default: true]: Whether teleporting across dimensions is allowed.
• world-ratio [default: 8]: The amount of blocks to divide the max warp range by during inter-dimensional teleports.
• warp-animations [default: true]: Whether to play a particle animation while the player waits to teleport.
• single-use [default: false]: Whether to dispose of the warp key once it is successfully used.
• require-power [default: INTER_DIMENSION]: Whether power is required for warping. Can be set to INTER_DIMENSION for only inter-dimensional travel, ALL for any warps, or NONE to disable.
• power-cost [default: 1]: How much power a warp will require if require-power is set to INTER_DIMENSION or ALL.
• enable-portal-sickness [default: true]: Whether players can be hit with a sickness effect if they teleport.
• portal-sickness-chance [default: 0.05]: The chance at which portal sickness can be applied to the player.
• portal-sickness-warping [default: DAMAGE_ON_TELEPORT]: Whether portal sickness has an adverse effect on warping. Can be set to PREVENT_TELEPORT to stop players from warping while sick, DAMAGE_ON_TELEPORT to allow players to warp but take damage from it while sick, or ALLOW to disable any adverse effects.
• portal-sickness-damage [default: 5.0]: The amount of damage (in heart pieces) taken by the user if warping while sick and DAMAGE_ON_TELEPORT is set.
• relinkable-keys [default: true]: Whether warp keys can be relinked after they are linked to a waystone.
• enable-key-items [default: true]: Whether to use a custom item for warp keys. This enables a custom crafting recipe for the item, and prevents normal compasses from being used as warp keys. If this setting is enabled later, compass warp keys should hopefully still work as warp keys.
• key-recipe [default: shown above]: The crafting recipe used for custom key items if custom keys are enabled.
• enable-advancements [default: true]: Whether advancements are enabled.

Commands

• /waystones: Provides info about the plugin
• /waystones getkey [ count | player [count] ]: Gives warp keys to players
• /waystones ratio [ set [name] [-environment] | remove [name] [-environment] | list ]: Manages the plugin's ratios
• /waystones config [property] [new value]: Allows users to view and update the plugin configuration
• /waystones info: Displays information about the plugin and its contributors
• /waystones reload [config | advancements]: Reloads the plugin's config or advancements.

Permissions

• waystones.link: Allows users to link waystones to a warp key
• waystones.getkey.self: Allows using the getkey command to give yourself a warp key
• waystones.getkey.all: Allows using the getkey command to give any player a warp key
• waystones.config: Allows viewing and modifying the plugin configuration
• waystones.reload: Allows reloading of the plugin configuration
• waystones.ratios: Allows use of the ratio command to manage teleport ratios

Advancements

As of version 1.1.0 we now include support for advancements! Below is a list of the advancements currently provided by Waystones.

• Waystones: Link a waystone to a warp key.
• Secret Tunnel: User a waystone for the first time.
• 1.21 Gigawarps: Travel over 50% of the max warp distance using a waystone.
• I Don't Feel So Good: Get hit with portal sickness from using a waystone.
• Heavy Artillery: Power up a waystone with a netherite block.
• Unlimited Power: Overcharge a waystone's power source causing it to explode.
• Quantum Domestication: Give a waystone a name.
• Blocked: Suppress a waystone with obsidian to prevent people from using it.
• Shoot The Messenger: Nearly die from a skeleton while attempting to warp away.
• Clean Energy: Use a waystone that's powered off the same energy source as a beacon.

waystones's Issues

locale lore multiline not possible

i would like to display the linked keys with a multiline in the lore. however, i have already tested several things. either it did not work or the lore was not completely visible.

I have done the following tests on my own:

link-key-lore: '&7linked to &e{0} \n &8[&7{1}&8]'

link-key-lore:
  - '&7linked to &e{0}'
  - '&8[&7{1}&8]'

link-key-lore: | 
  &7linked to &e{0}
  &8[&7{1}&8]

link-key-lore: |-
  &7linked to &e{0}
  &8[&7{1}&8]

link-key-lore: >
  &7linked to &e{0}
  &8[&7{1}&8]

link-key-lore: >-
  &7linked to &e{0}
  &8[&7{1}&8]

At the 1st attempt no error came but \n was displayed in the lore ingame.
With the 2nd example an error came because of YAML formatting.
In the other examples only the 1st line was displayed. The 2nd was not visible / present.

Can you help me? or does the function not yet exist? ^^

[Enhancement] Configurable Boost Blocks

How difficult do you think it would be to add configurable boost block types / percentages?
I'd be willing to write the change if you'd point me in the write direction.
I don't have much (any lol) Kotlin experience, but I assume it would be something like:

• Parse list of "block string"/"boost percent double" pairs from config
• Convert the list to map of Material to Double
• Create a more generic function similar to your *Boost functions which calculates Int = (maxBoost() * blockToPercentMap([block.type]).toInt())

Just thinking out loud. Let me know what you think and thanks for your hard work!

Key Item Crafting Recipe

Hello, it seems like the actual crafting recipe is hard to find. Including it as an image in the README would help a lot. Having it shoved deep in the code seems quite challenging to find https://github.com/AtriusX/Waystones/blob/master/src/main/kotlin/xyz/atrius/waystones/data/crafting/CompassRecipe.kt

Furthermore, we'd like to see being able to actually customize the crafting recipe to our own needs.
Thank you.

Redo the link-no-permission error message to be a bit easier to understand

It was brought to my attention over on the spigot resources page that the error message for when a key cannot be linked was a bit too confusing. Having considered it, I think it would likely be wise to redo and re-translate it so that players understand the intent more clearly.

The wording of this new message has yet to be determined. Any suggestions are welcome. For context, this was the previous error message.

Waystones/src/main/resources/locale-en.yml

Line 41 in bb18cbb

link-no-permission: "This link has severed and rotted away..."

Allow worldguard region to be discovered

I would like to see a feature in which when a player enters a worldguard region, it automatically gets the option to warp to a lodestone of that particular area. (Set by the user)

Running /waystones getkey in console causes an exception instead of sending an error.

Just as the title says, running /waystones getkey in the console window causes an error to occur instead of printing an error. A simple fix for this would be to just limit the command to players but I feel that this would be a bit too restrictive.

Localization updates needed

A recent update to the repository requires an update to the current plugin locales.

The following changes were made:

• added command-config-invalid-prop

command-config-invalid-prop: "&7[&dWaystones&7] &cSetting {0} does not exist."

• updated warp-error-unpowered

warp-error-unpowered: "{0} does not currently have enough power"

@NewbieOrange Once these updates are made I should be able to push the update to spigot.

Warp range inconsistency between dimensions

Current range calculations regarding interDimension are broken, due to the worldRatio division being done on the range of the waystone, rather than the distance the player is and the relative location of the waystone to the origin of the world.

There is a temp fix with Nether -> Overworld warping, though it is still inconsistent with Overworld -> Nether warping and doesn't account for other dimensions, especially considering 1.16 allows various dimensions to be added through Data Packs.

// handler/WaystoneHandler.kt | Line 29
override fun handle(): Boolean {
    error = state.message(name)
    return when (state) {
        is Active, is InterDimension -> {
            // Calculate warpLocation based on interDimension
            // Exclusively works with Nether -> Overworld teleportation
            val warpVector = if (interDimension) {
                warpLocation.toVector().divide(Vector(8, 1, 8))
            } else warpLocation.toVector()

            // Calculate range and distance from warp
            val range = state.range
            val distance = location.toVector().distance(warpVector)

            if (distance > range) false.also {
                error = distanceError(name, distance, range)
            } else true
        }
        is Inhibited -> false
        else -> error == null
    }
}

However, the current way of detecting and returning player dimension location causes problems, in general. Due to variable worldRatios and the inability to calculate it in reverse. This is because the true/false return, in Location.sameDimension, is not enough information to specify player dimensional location. This is causing an issue with nether and end dimension waystone range, and could elicit a rework of the interdimensional function.

// utilities/Location.kt | Line 69
fun Location.sameDimension(other: Location) =
    world == other.world ?: false

Configurable Messages File

It could be nice to have a YML file dedicated to configuring the messages displayed by the plugin for various actions, such as initiating a warp, successfully warping, canceling a warp, or getting info of a waystone. This could also be expanded to include the lore on linked Warp Keys.

These would just be simple string values within the file, utilizing some placeholders available through Waystones depending on context, such placeholders could be

%waystones_outofrange% - How far out of range a player is from Waystone
%waystones_distance% - Player's total distance from Waystone
%waystones_name% - Name of Waystone in question
%waystones_range% - Range a Waystone is capable of being teleported to from
%waystones_status% - Active status of Waystone, seen in InfoEvent
%waystones_coords% - Coordinates of Waystone, as seen in current WarpKey lore
%waystones_countdown% - Countdown during warmup to Waystone warp

These wouldn't have to be global like CMI or PlaceholderAPI, but rather just available through this messages config, the messages would then be parsed to replace these instances when used within the actual events.

This could also allow for custom color codes to be used, though that may require some refactoring of the Player.sendActionMessage() function within PlayerUtils.kt

---

The message file could look something like

InfoMessage: "&bName: %waystones_name% | Status: %waystones_active% | Range: %waystones_range%"
InitWarpMessage: "&aWarping to %waystones_name% in %waystones_countdown% second(s)"
CancelWarpMessage: "&cWarp cancelled"
OutOfRangeMessage: "&c%waystones_name% is out of range (%waystones_outofrange% block(s))"
# etc. etc.

---

Slightly unrelated, but this could also open up to the idea of localization, with locale files in a directory holding the messages in different languages. Though I'm unsure as to how this is actually implemented.

Commands to List and Teleport to active waystones

Mostly some QoL for administration.

A command to list all "active" waystones, in concert with a command to teleport to said waystones.

• "active" being any waystone that is present in the world and has had a warpkey linked to it. (waystones.list)
• Ideally, the waystones would save who did the first link so we can see its original creator so to speak (waystones.teleport)

just something i thought of as i could not see all the waystones in the world only ones that players have named.

Using XP based on range

I'd like to see an option where warping consumes XP based on either distance or if there is a dimension jump involved!

IE: an overworld warp would be 1-3 levels based on distance and a warp from overworld to end would be 5 levels

Check Building Perms before Linking

It would be nice to require the ability to build in order to link, this would prevent not only linking within lobbies/hubs of servers, but also stop linking to someone's waystone in a house claimed through some grief prevention plugin.

While I was hoping this could be done through linking into something such as Vault, it doesn't seem to support this specific type of permission, as it seems most plugins just cancel/override the event within themselves internally based on various things that aren't always so externally accessible, such as WorldGuard checking a specific flag within the region the player tries to place a block.

The most reliable way to do this without hardcoded support for certain plugins seems to be through a simulated block place event. When linking, simulate the placement of a block at the location of the waystone, if the placement was cancelled (likely by some other plugin) then they're not able to build there and the LinkEvent fails, likely with some sendErrorMessage being called to the inform the player they don't have permission.

I found a small forum post that briefly suggests this, I'll link it once I find it tomorrow.

Localization throws exception when config localization is set to an invalid setting

This seems to be intended behavior based off the current implementation of Localizations, however I am debating on whether or not this should be changed to be a bit more clear to users. Exceptions aren't very helpful to people who don't know how to read them, so maybe it might be a better idea to default to english and return an error message in the console instead of completely breaking.

It also appears that an exception is thrown if english is not present in the jar file for whatever reason (this happened to @NathanAdhitya while testing #27 apparently). I don't feel like this specific part of behavior should change, since it reflects a problem with the jar file itself, but I'm open to alternative ideas if offered.

Save waystone locations

Currently, the plugin tries to be as hands-off as possible with waystone locations as possible. However in the future it will likely be important that we have access to all waystones currently active on a server all at once (such as in the case of #47).

The implementation of this could mirror the same simple JSON files we have already, however it may also become necessary at some point to consider the possibility of database support. In order for a smooth transition to occur, it might make the most sense for this feature to be included in a patch update (1.1.1 perhaps) so that servers will have a bit of time to adjust and track existing waystones.

Attention will also need to be given to determine the factors for when a waystone should be created or destroyed. It should also be discussed if we should migrate away from the existing warpnames.json file used for name storage. If we implement location storage for all waystones, then it might make more sense to simply merge the names file with the new one to avoid excess file creation.

Taking any damage causes "Teleportation Cancelled" message to display

When taking any form of damage, the "Teleportation cancelled" message shows, despite not having a teleportation queued.
This was happening prior to the restructure and the fix in 45db3e3 didn't get moved over it seems.

Error while enabling Waystones

So I downloaded your repository and built the .jar file manually, (after some research because i never worked with gradle) and now when trying to start the server, the plugin isn't loaded correctly (I built the .jar on windows but that shouldn't be an issue afaik)

Teleportation (somewhat) broken for Server Operators

Hello,

I've been using this plugin without issue for several days and things have been pretty great. Suddenly, today, with no changes or updates, waystones has been... misbehaving. I've posted an example to youtube.

https://youtu.be/0v78yIKFtOc

A rundown of the issue is as follows:
Right Clicking attempts to teleport you to some number of blocks in front of where your cursor is. This is shown when I am teleporting but my compass is not moving.
Left Clicking does... something. I'm honestly not sure exactly where it's teleporting me to. That is when it moves the compass.

Both of these things only happen when I'm server operator. As shown in the video, deopping fixes the issue. ReOpping breaks it again.

I tried to compile the plugin myself locally so that I could try to debug it myself, however I cannot get the resulting jar to run. I'm opening it in IntelliJ and using the provided gradle settings to generate the Jar. the resulting error is as below.

java.lang.NoClassDefFoundError: kotlin/jvm/internal/Intrinsics
at xyz.atrius.waystones.WaystonesKt.setPlugin(Waystones.kt) ~[waystones-1.1.0.jar:?]
at xyz.atrius.waystones.Waystones.onEnable(Waystones.kt:25) ~[waystones-1.1.0.jar:?]
at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:264) ~[paper-api-1.18.1-R0.1-SNAPSHOT.jar:?]
at org.bukkit.plugin.java.JavaPluginLoader.enablePlugin(JavaPluginLoader.java:370) ~[paper-api-1.18.1-R0.1-SNAPSHOT.jar:?]
at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:500) ~[paper-api-1.18.1-R0.1-SNAPSHOT.jar:?]
at org.bukkit.craftbukkit.v1_18_R1.CraftServer.enablePlugin(CraftServer.java:563) ~[paper-1.18.1.jar:git-Paper-71]
at org.bukkit.craftbukkit.v1_18_R1.CraftServer.enablePlugins(CraftServer.java:477) ~[paper-1.18.1.jar:git-Paper-71]
at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:727) ~[paper-1.18.1.jar:git-Paper-71]
at net.minecraft.server.MinecraftServer.loadLevel(MinecraftServer.java:503) ~[paper-1.18.1.jar:git-Paper-71]
at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:313) ~[paper-1.18.1.jar:git-Paper-71]
at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1202) ~[paper-1.18.1.jar:git-Paper-71]
at net.minecraft.server.MinecraftServer.lambda$spin$0(MinecraftServer.java:317) ~[paper-1.18.1.jar:git-Paper-71]
at java.lang.Thread.run(Thread.java:833) ~[?:?]
Caused by: java.lang.ClassNotFoundException: kotlin.jvm.internal.Intrinsics
at org.bukkit.plugin.java.PluginClassLoader.loadClass0(PluginClassLoader.java:151) ~[paper-api-1.18.1-R0.1-SNAPSHOT.jar:?]
at org.bukkit.plugin.java.PluginClassLoader.loadClass(PluginClassLoader.java:103) ~[paper-api-1.18.1-R0.1-SNAPSHOT.jar:?]
at java.lang.ClassLoader.loadClass(ClassLoader.java:520) ~[?:?]
... 13 more

Server is PaperMC 1.18.1 using your latest plugin 1.1.0. Server OS is Debian based, MineOS. Java version is OpenJDK version 17.0.1.
Local dev machine is Arch Linux, openjdk 17.0.1

Can you

1. create a section of your readme that explains your environment setup/how to set up to help contribute if someone would like to? and/or
2. let me know what would I can do to help debug this issue, if anything further than already done.

Thanks

Discussion for the inclusion of a plugin API.

Recently there has been a bit of interest surrounding the need for integration with world protection plugins to ensure that waystones in the system cannot be misused (see PR #14). On top of this we should consider the ideas presented in Issues #19 and #20 as ideas beyond the scope of this project, but otherwise worth offering support for.

The purpose of this issue is to discuss what we should look for in an API. At this point it is clear we will need a standard one to expose access to some information about waystones within the system. It's also clear that an API will need to exist to offer first-class support to plugins like WorldGuard, and second-class support to other plugins.

What we need to consider is what both of these components will need and how we should implement them. Any ideas are welcome.

Suggestion: Pl3xmap Support

I would like to see a Pl3xmap support for the plugin, so that you can see the waystones when placing them on the online map and possibly a better locate or manage can take place.

Pl3xmap:
OLD <= 1.17: https://github.com/pl3xgaming/Pl3xMap
NEW > 1.17: https://github.com/NeumimTo/Pl3xMap or https://github.com/jpenilla/squaremap

Inconsistent ConfigCommand regarding values with PercentageParser

Config values with a PercentageParser applied require a percentage symbol after the value when setting them through ConfigCommand, though this is never displayed by the command itself when listing values.

Strangely, trying to the portal-sickness-chance value to 0.05%, which is its default and is followed by a percentage sign, still fails for an unknown reason, as setting it to 0.01% works fine.

link-no-permission: This link has severed and rotted away...

friend made a waystone and when he tries to link it says link-no-permission: This link has severed and rotted away...

Infinite warp range not working

After placing a commandblock under the waystone, it becomes unusable even at minimal distance.

Global warps

Is it possible for you to add a /warp command which opens a gui that lists all the warps player has discovered, and allow to tp to those warps.
You can check my other feature request to see how can you implement discovering of these warps. You can also add a /addwarp command that enables us to add a particular warp to a player warp list.You can make it so server owners can select the icon of the warp(with player skull and custom model data support).