diff --git a/README.md b/README.md index 121f074f..36ad41ce 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,140 @@ +# Waystones [![Badge](badge/support.svg)](https://hangar.papermc.io/Atri/Waystones) [![Paper](badge/paper.svg)](https://papermc.io/) [![Kotlin](badge/kotlin.svg)](https://kotlinlang.org) -# Waystones [![Badge](badge/support.svg)](https://www.spigotmc.org/resources/waystones.93917/) [![Paper](badge/paper.svg)](https://papermc.io/) [![Kotlin](badge/kotlin.svg)](https://kotlinlang.org) - -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)**, **Waxed Copper Block (30% Boost)**, **Other Copper Blocks (25% 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: - -Warp Key Recipe - -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](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) 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. \ No newline at end of file +## Overview +Waystones is a Minecraft plugin designed to integrate teleportation into the survival experience. In many other servers, the use of commands like `/tp` or `/home` can feel overpowered or out of place, stripping away the immersion of utilizing gameplay features to get around. + +Waystones addresses this by introducing an item-based teleportation system. By making use of Lodestones and Warp Keys, players can establish a network of fast-travel points across their world. This encourages players to build infrastructure to enable easier fast travel throughout their worlds. + +--- + +## A Guide to Teleportation + +### Establishing A Waystone +Teleporting with Waystones requires crafting items and building physical structures in your world. + +**1. Obtain a Warp Key** +Depending on how you have set up your server, these can be crafted using the recipe provided below or by crafting a normal compass. If the `enable-key-items` configuration option is enabled, you'll be able to craft it via your servers configured crafting recipe. + +The default recipe is as follows: + +| | Column 1 | Column 2 | Column 3 | $\rightarrow$ | Result | +| :---: | :---: | :---: | :---: | :---: |:-------------------------------------------------------------------------------------------------------------:| +| **Row 1** | $\text{ }$ | Iron Ingot | $\text{ }$ | | | +| **Row 2** | Iron Ingot | Redstone Block | Iron Ingot | $\rightarrow$ | Warp Key | +| **Row 3** | $\text{ }$ | Iron Ingot | $\text{ }$ | | | + +**2. Create a Waystone** +Place a Lodestone at a location of your choosing. To link your warp key, right click the Lodestone using the key. Once linked, the item in your hand is tethered to that specific location, until the waystone itself is destroyed. + +**3. Warping** +Whenever you wish to return to a fast-travel point, simply right-click the linked Warp Key in your inventory. You will enter a short waiting period (if configured by the server) before being sent back to the location linked to the key. + +### Waystone Structures + +**Boosting Your Range** +By default, waystones have a limited reach, but you can expand this range by reinforcing the area around your waystone with precious materials. The values in the table below are based on a percentage of your server's configured max-boost property and can be accumulated until you reach the number of blocks equal to your server's configured max-warp-size. + +| Material | Boost | Description | +| :--- | :--- | :--- | +| **Netherite** | Maximum | Applies the maximum range, though hard to acquire | +| **Emerald** | 75% Boost | Highly efficient, and easier to get via trading | +| **Diamond** | 50% Boost | Half as effective as netherite, but easier to acquire via mining | +| **Gold** | 33% Boost | Moderate boost, useful for more localized travel | +| **Waxed Copper (Unoxidized)** | 30% Boost | Clean copper gets a slight boost over unwaxed copper of any other variety | +| **Copper** | 25% Boost | Provides a basic but economical boost, good for early game investment | +| **Iron** | 20% Boost | 1/5 as efficient as Netherite, good if you just need a small bump | + +**Powering Inter-Dimensional Travel** +Crossing the boundaries between the Overworld, the Nether, and the End requires significant energy. When power requirements are enabled, you must place a **Respawn Anchor** beneath your waystone. Waystones will only function as long as the anchor remains charged. For some addtional convenience, some servers may choose to disable or reconfigure the power cost required to use a waystone. + +**The Cost of Convenience: Portal Sickness** +Teleportation can be a taxing process on the body. There is a random chance that a player will arrive at their destination suffering from **Portal Sickness**. + +| Effect | Duration | Detail | +| :--- | :--- | :--- | +| **Nausea X** | 30 Seconds | Distorts the player's vision. | +| **Blindness** | 5 Seconds | Severely limits visibility. | +| **Physical Toll** | Variable | May prevent further warping or cause damage if warping while sick. | + +**Maintenance** +* **Naming**: Use a Name Tag on your waystone to give it a custom name, making it easier to manage multiple links. +* **Suppression**: If you wish to disable a waystone—perhaps to hide a secret base—place **Obsidian** beneath the lodestone to suppress its functionality. + +--- + +## Admin Tools + +### Installation +Be sure to shut down the server before installing the plugin (if it's currently running) + +* **Supported Platforms**: Paper-based servers are the only supported installations at this time. +* **Process**: Simply download the plugin JAR and place it into your server's `plugins` directory. + +### Commands and Permissions +The following table outlines the commands available to manage the plugin: + +| Command | Description | Permission | +| :--- | :--- | :--- | +| `/waystones` | Displays general plugin information | `N/A` | +| `/waystones getkey [count\|player]` | Grants warp keys to specified players | `waystones.getkey.all` / `waystones.getkey.self` | +| `/waystones ratio [set\|remove\|list]` | Manages teleportation distance ratios | `waystones.ratios` | +| `/waystones config [prop] [val]` | Views or updates configuration properties | `waystones.config` | +| `/waystones info` | Displays contributor and plugin details | `N/A` | +| `/waystones reload [type]` | Reloads configuration or advancements | `waystones.reload` | + +### Configuration + +
+Click to view detailed configuration properties + +| Category | Property | Description | +| :--- | :--- | :--- | +| **Distance & Range** | `limit-distance` | Enable/disable the range limit. | +| | `base-distance` | The default range of a waystone without boosts. | +| | `max-boost` | The maximum additional distance granted per boost block. | +| | `max-warp-size` | Limits how many boost blocks can be utilized. | +| | `world-ratio` | A divisor applied to range when teleporting across dimensions. | +| **Power & Cost** | `require-power` | Determines if anchors are needed (ALL, INTER_DIMENSION, or NONE). | +| | `power-cost` | The amount of charge consumed from an anchor per warp. | +| **Portal Sickness** | `enable-portal-sickness` | Toggles the sickness mechanic. | +| | `portal-sickness-chance` | The probability (0.0 - 1.0) of contracting sickness. | +| | `portal-sickness-warping` | Behavior when sick (PREVENT_TELEPORT, DAMAGE_ON_TELEPORT, ALLOW). | +| | `portal-sickness-damage` | Damage dealt to sick players during a warp. | +| **General Behavior** | `wait-time` | The delay in ticks before teleportation occurs. | +| | `damage-stops-warping` | If true, taking damage cancels the warp sequence. | +| | `single-use` | If true, warp keys are consumed upon use. | +| | `relinkable-keys` | Allows players to link a key to a different waystone. | +| | `enable-key-items` | Toggles the custom item and crafting recipe. | +| | `locale` | Sets the language file for in-game messages. | +
+ +### Built-in Advancements +To enhance the vanilla experience, Waystones offers a collection of achievements that the player can earn: + +| Achievement | Requirement | +| :--- | :--- | +| **Waystones** | Link your very first waystone. | +| **Secret Tunnel** | Complete your first successful warp. | +| **1.21 Gigawarps** | Execute a warp covering over 50% of the maximum possible distance. | +| **I Don't Feel So Good** | Suffer the effects of portal sickness. | +| **Heavy Artillery** | Use Netherite to maximize a waystone's power. | +| **Unlimited Power** | Trigger an explosion by overcharging a power source. | +| **Quantum Domestication** | Give a waystone a unique name. | +| **Blocked** | Successfully suppress a waystone using obsidian. | +| **Shoot The Messenger** | Nearly perish to a skeleton while attempting to warp. | +| **Clean Energy** | Utilize a waystone powered by a beacon source. | + +--- + +## Contributing +You can help improve the project by contributing in the following ways: + +* **Development**: Submit bug fixes or new feature implementations via Pull Requests on GitHub. +* **Translations**: Provide or refine translations for the localization files to support more languages. +* **Reporting**: Use the GitHub issue tracker to report bugs or suggest improvements. + +### Support +If you find Waystones useful and wish to support its continued development, you can: + +* **Donate**: You may support the project financially through [GitHub Sponsors](https://github.com/sponsors/AtriusX) or [PayPal](https://paypal.me/Atrius). +* **Recommend**: Share the plugin with other server administrators and players. diff --git a/badge/support.svg b/badge/support.svg index 35db9a8e..71ca53ce 100644 --- a/badge/support.svg +++ b/badge/support.svg @@ -1 +1 @@ -WAYSTONES1.21 \ No newline at end of file +WAYSTONES26.1 \ No newline at end of file