purpurmc/purpurdocs

This is the documentation for Purpur that uses Mkdocs to generate a static site

PurpurDocs

This is the documentation for Purpur that uses Mkdocs to generate a static site hosted on https://purpurmc.org/docs. Included is a Python script that compares the diff of two commit hashes and outputs the config/permission additions/removals into a YAML file.

Building

Create and activate a Python 3 virtual environment

$ pip install --user virtualenv
$ virtualenv env
$ source env/bin/activate

Install the required packages

pip install -r requirements.txt

Preview changes

To preview your changes to the documentation, run mkdocs serve. This will start a web server that will preview the documentation and recompile it as you make changes. More info is shown here: https://www.mkdocs.org/#getting-started

$ mkdocs serve

Compare commits for config/permission additions/removals

Run the compare-commits.sh script to run an interactive script that compares between Purpur commits and generates a file of config option/permission additions/removals.

./compare-commits.sh <prev_hash> <curr_hash>

You can also add two commit hashes as command line arguments and it will skip the interactive aspect of the script.

$ ./compare-commits.sh 885092 22b876

# logs/885092..22b876.yml

config:
  additions:
  - gameplay-mechanics.item.immune.cactus: new ArrayList<>()
  - gameplay-mechanics.player.fix-stuck-in-portal: 'false'
  removals:
  - projectile-load-save-per-chunk-limit: '-1'
permission:
  additions: []
  removals: []

./compare-commits.sh <prev_hash>

Including only one hash will compare it to the latest commit of the branch specified (which is `ver/1.16.5` at the time of writing).

$ ./compare-commits.sh 885092

# logs/885092..ver|1.16.5.yml

config:
  additions:
  - gameplay-mechanics.item.immune.cactus: new ArrayList<>()
  - gameplay-mechanics.player.fix-stuck-in-portal: 'false'
  removals:
  - projectile-load-save-per-chunk-limit: '-1'
permission:
  additions: []
  removals: []

./compare-commits.sh --no-commits

Running the script with the option `--no-commits` or `-nc` will create a `last_commit` file that includes the most recent commit at runtime. Running it again will make it use the hash located in `last_commit` as the first commit hash, replacing it with the most recent commit after generating the file.

# First time running it
$ ./compare-commits.sh -nc

# logs/885092..ver|1.16.5.yml

config:
  additions:
  - gameplay-mechanics.item.immune.cactus: new ArrayList<>()
  - gameplay-mechanics.player.fix-stuck-in-portal: 'false'
  removals:
  - projectile-load-save-per-chunk-limit: '-1'
permission:
  additions: []
  removals: []

# Creates a last_commit file
885092

# Running it again after new commits are pushed to Purpur
$ ./compare-commits.sh -nc

# logs/885092..22b876.yml

config:
  additions:
  - gameplay-mechanics.item.immune.cactus: new ArrayList<>()
  - gameplay-mechanics.player.fix-stuck-in-portal: 'false'
  removals:
  - projectile-load-save-per-chunk-limit: '-1'
permission:
  additions: []
  removals: []

# Modifies the last_commit file
22b876

purpurdocs's Issues

[WRONG INFO] Wrong description at 'uptime-command-output'

uptime-command-output
Requires the bukkit.command.uptime permission - The format from .command.uptime.format
default: <green>Server uptime is <uptime>
description: Actionbar message that shows when someone attempts to run with scissors

I don't think uptime-command-output is related to running with scissors (Actionbar message that shows when someone attempts to run with scissors).
I think it is copy & pasted from the lines below, dont-run-with-scissors.

Since I can't think of correct phrase for correcting this, I will just post an issue of that.

Document the available arguments in each format option

in Java there is a String formatter which allows variables (like %s) to be used as placeholders. s being the placeholder for String. since it does not contain a specific number, it will use them in order from first to last.

String.format("Hello %s! %s name is %s!", "world", "My", "Billy");
// Outputs: "Hello world! My name is Billy!"

You can specify the argument numbers like so:

String.format("Hello %3s! %1s name is %2s!", "world", "My", "Billy");
// Outputs: "Hello Billy! world name is My!"

There are other argument types than String, but that's all we use in Purpur's config.
To know what arguments are available, you can check out the source code to document them.

using ping-command-output as an example it could be formatted something like this:

ping-command-output

• default: §a%s's ping is %sms
• description: Output when /ping is run.
  %s - uses the values below in order from first to last
  %1 - player's name
  %2 - player's ping in ms

Update links and endpoints to v2 of the API

Links and endpoints on the documentation home page should be updated to reflect the new API version 2. The links for 1.17 and 1.17.1 should also be added.

GIFs under each option

Each option would have a dropdown GIF that would need to be opened up using the details disclosure element. This would make sure the docs don't get bloated from all the gifs while also making it possible to view if the user would like to see the option in action.

Example:

📷 GIF of option in action

Feature Request - Use of multiple world seeds. Biome/Cave/World Height

Not sure if this is entirely possible, but I thought it would be interesting.

video on it

https://www.youtube.com/watch?v=BbGUHAUfpv4

Collapsible Table of Contents

It's not something that can simply be enabled in the config file. Functionality would be similar to how the navigation section can be made collapsible.

We could either:

• Find (or create) a mkdocs plugin that gives us this ability
• Override the Material theme's partials/toc-item.html and replicate the navigation bar's dropdown menu ability
  • an arrow to the right of the toc item that expands/collapses the items inside it
  • the toc item itself still jumps you to the header that it's connected to
• Wait for this to become a feature in the Material theme (which will probably never happen)

Add more to the Home page

I'm not really sure what could be added currently but it's pretty barren right now.

Some ideas include:

• more info about Purpur
  • FAQ
  • Javadoc
  • bStats
  • Downloads page
  • link to website
  • etc
• links to other resources
  • YouHaveTrouble's guide
  • etc

Add food-properties documentation

title

Meta tags for each option header

Since you cannot assign meta tags based on URI fragments, create a custom page for each option that redirects you to the location of that option in the Configuration page.

Using the verbose option as an example from the docs,

https://purpurmc.org/docs/Configuration/#verbose
would be the original link to the option, and

https://purpurmc.org/docs/Configuration/verbose
would be used for meta tags that describe the option whilst also redirecting you to the original link when opened. The hyperlink 🔗 icon next to the option name would use window.history.pushState to replace the link in the address bar with the new page whilst also keeping the "jumping to header" functionality using Element#scrollIntoView() to encourage usage of this new feature.

The only reason I want this functionality is so that posting a link to the option will display an embed in discord with the information on that option. It's a lot of work for minimal gain, which is why I don't see this happening anytime soon.

A patches page

This page would explain every patch that Purpur adds with a categorized list of the feature, performance stuff, API stuff, etc.

It would be categorized by api & server, with headers being the filename of the patch. Each patch would include a hyperlink to the patch in Purpur.

/patches
## api
  ### This-Is-A.patch
    description:
    reason?:
    permissions:
    options:
  ### This-Is-Another.patch
    description:
    reason?:
    permissions:
    options:
## server
  ### This-Is-A.patch
    description:
    reason?:
    permissions:
    options:
  ### This-Is-Another.patch
    description:
    reason?:
    permissions:
    options:

Truncating the number from the filename would make it less difficult to keep it up-to-date with Purpur incase patches get reorganized or renamed.

• description will explain what that patch does
• reason will explain why this patch was added
• permissions will list any permissions that the patch adds
• options will list any options that the patch adds

Not really sure how to format this page but these are my inital thoughts. The format may change from what is listed here depending on feedback from others or how it looks in the end.

Mobs don't look where they're WASD walking when being ridden. ( Ravagers )

Looking with the mouse re-orients them, but any WASD movement locks them to a specific [ 135.0, 0.0 ] rotation while moving.
Unsure if this is for more mobs or limited to the Ravager.

Additionally the riding speed seems slow, can this be increased to match the vanilla mob's movement speed or a parameter provided? Also shouldn't they have a special move since they have the head-bash attack?

Missing setting

This exists in config files, but i guess it is missed in docs
config path is gameplay-mechanics.arrow.movement-resets-despawn-counter

Internal Exception while using waterfall with 1.19.2

While using 1.19.2, I get an internal error while using waterfall proxy. I have never gotten or heard of this error before, but I have looked at every config, downgraded the server back to 1.19, and reinstalled both waterfall and purpur multiple times. The error is this:

Internal Exception: java.lang.NoSuchMethodError: 'com.mojang.authlib.GameProfile net.minecraft.world.entity.player.EntityHuman.fz()'

I run a community server and need to update it to support some of my plugins.

player_interacted_with_entity advancement trigger does not work on entities

When using player_interacted_with_entity in an advancement it should trigger upon right clicking a right clickable entity. This happen in other versions but not purpur.

Prove it by:

1. Summon an non-ai villager (ai and non-ai is the same): /summon minecraft:villager ~ ~ ~ {NoAI:1}
2. Download the following datapack: testing.zip
3. Right click on the villager and you should see 2 chat message when the advancement triggers.

Descriptions for the nether wart and sugar cane affected by bonemeal settings were copy and pasted from the cactus one.

explosion-effect config description inconsistency

Hi, I want to report inconsistency in the documentation vs actual server value
https://purpurmc.org/docs/Configuration/explosion-effect_2

Key: end-crystal.*.explosion-effect (and possibly others like respawn anchor or bed in the nether)

It is said in the documentation

explosion-effect
default: DESTROY
description: The type of explosion effect. Available values are NONE, BREAK, and DESTROY.

But when I try to set it to "BREAK" it is not accepted by the server:

[09:05:13 ERROR]: Unknown value for blocks.end-crystal.baseless.explosion-effect! Using default of BLOCK
[09:05:13 ERROR]: Unknown value for blocks.end-crystal.base.explosion-effect! Using default of BLOCK

Also in the documentation, the "BLOCK" option is nowhere to be seen in any config.

Composter bulk process feature

Hello there. I have an misunderstanding with a composter sneak-to-bulk-process feature.

Enabled in purpur.yml

composter:
        sneak-to-bulk-process: true

And when i sneak and right-clicking with stack of sufficient item nothing happens.
What am i doing wrong?