I noticed in my server's global config there is now a player-max-chunk-generate-rate option. However, I have no idea what this option is. Like, the name is obvious enough, but what does the value mean? It's not on the PaperMC documentation and searching the PaperMC organization and codebase returns only a few issues with users posting their configurations and it being in them.

What does the value mean, and at what "rate" does the value refer to? Obviously I presume -1 is no limit. This option could be incredibly helpful for my server as it can load chunks very quickly but new generation is particularly slow.

https://docs.papermc.io/paper/aikars-flags#using-large-pages

-XX:+UseLargePagesInMetaspace

https://bugs.openjdk.org/browse/JDK-8243161
Is anyone still using Java 8 with Paper?

Kind of a one stop shop kinda deal with an intro on why stuff is different (history of cb/spigot, why do we fix exploits, tradeoffs for performance), some example of what is different and a list of all config options with copy-paste examples (with links to the config page) we suggest tweaking to get closer to vanilla again

The Paper docs should have a page for developers that lists all dependencies that are included within Paper's API for a developer to access and use.

It would help in keeping the jar file small by knowing what libraries are present and provided and which need to be included, either by shading in or by using the PluginLoader itself.

It can also help answer questions like "Is this dependency included?" which I myself had recently regarding the Adventure Legacy Serializer.

Wanted to open this issue first before Blatantly opening a PR, to see if there is a need for it and to discuss a possible design for the page.

The link incorrectly points to https://papermc.io/javadocs when it should point to https://jd.papermc.io.

Currently only the paper default and world configuration files are documented. The server generated other configs like bukkit.yml, spigot.yml and commands.yml too though so they should probably be documented as well. (Or at least linked in an obvious place)

Paper also adds values to those files (e.g. the wake-up-inactive for the entity activation range in spigot.yml is from Paper improvements to that feature) so at least those should be mentioned in the Paper docs.

Ideally for both paper and spigot/craftbukkit

bar this commit message (PaperMC/Paper@e0ea2e0) entity activation range changes made by paper aren't documented.

Would be good to have docs here for both specific configs as well as generally explaining the concept of EAR.

i want to remove anti xray for spectators is there a way to do that because my admins are complaining about it

https://docs.papermc.io/velocity/dev/creating-your-first-plugin
https://github.com/PaperMC/docs/blob/main/docs/velocity/dev/getting-started/creating-your-first-plugin.md

The problematic lines:

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

Somehow the favicon is not visible/not found from Firefox. The network analyze tool indicates a wrong search location for the favicon.ico: https://docs.papermc.io/img/favicon.ico - the favicon.ico can be found in https://docs.papermc.io/favicon.ico.

This bug is not reproducable on Chrome and Chrome based browsers because they use the icon-144x144.png (or smaller pngs) in the img directory.

The page(Link here ) implies that utilising inventory.getHolder() is good practice for an initial check for an InventoryClickEvent. This is quite poor practice and can lead to a gross amount Blockstate snapshots being created and, in the case of TileEntities, an equal amount of Inventory snapshots.

As this is an initial check, it would mean every inventory within the server that implements a plugin that utilises this practice, would have significant thread utilisation on creating these snapshots for every click of any inventory.

As such, I request that, at the least, the "false" boolean is added to the page. More ideally, some more elaboration on why this is bad practice would be nice.

I think a history page that gives a general overview of how Paper game into being. Maybe something similar for Velocity, although that doesn't have as direct ancestors as Paper does. Just to kind of have a single place to point to.

There is a section in https://docs.papermc.io/paper/aikars-flags, that says if you has 12G+ memory, you should adjust flags a little.

Script Generator completely skips that part and just pastes static flags.

Instead of having 1 header with dropdowns for each project and each project's categories, have 1 project dropdown on the left to switch between Paper, Velocity, Folia, and Waterfall. Then the buttons in the header can link to each category of documentation, Administration, Development, Contributing.

Then the sidebars for each of those categories can be simplified to only show docs in those categories instead of showing all the docs for paper, or all of velocity which it currently does.

I feel that most people aren't looking at administration and development docs for a project at the same time, so splitting them up unclutters the sidebars.

The bukkit.yml has an optional worlds section that currently isn't documented, it's used for changing the generator/biome provider for specific worlds to ones from plugins

Example:

worlds:
  world:
    generator: pluginname:generator
    biome-provider: pluginname:biomeprovider

The Plugin Messaging doc is missing the MessageRaw subchannel.
https://www.spigotmc.org/wiki/bukkit-bungee-plugin-messaging-channel/#messageraw

Crossref for PaperMC/Paper#10312

We should have a page which serves to get new server owners into some level of swing, this will mostly be a point of leading server owners to more dedicated guides in a friendly manner, but, may also decide to contain some general recommendations, i.e. how to whitelist, for example.

Not 100% sure what a good onboarding page would contain, however, that is probably a discussion point here

Reference documentation for server.properties, specifically, note how specific options are only applied for any world creation, while others are only used for primary world creation, and yet others are applied at all times, regardless of world.

Relates to PaperMC/Paper#7570

in the script showed here it asks for a project entry but uses it only once and does not implement it in the way that it could support all projects.

this is the script listed on the docs:

#!/bin/bash

PROJECT="paper"
MINECRAFT_VERSION="1.20.4"

LATEST_VERSION=$(curl -s https://api.papermc.io/v2/projects/paper | \
    jq -r '.versions[-1]')

LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds | \
    jq -r '.builds | map(select(.channel == "default") | .build) | .[-1]')

JAR_NAME=paper-${LATEST_VERSION}-${LATEST_BUILD}.jar

PAPERMC_URL="https://api.papermc.io/v2/projects/paper/versions/${LATEST_VERSION}/builds/${LATEST_BUILD}/downloads/${JAR_NAME}"

# Download the latest PaperMC version
curl -o server.jar $PAPERMC_URL
echo "Downloads completed"

Let me list the flaws

1. line 5: LATEST_VERSION=$(curl -s https://api.papermc.io/v2/projects/paper | \ the url is hardcoded to the paper project
2. line 12: JAR_NAME=paper-${LATEST_VERSION}-${LATEST_BUILD}.jar the filename is hardcoded to the paper project
3. line 14: PAPERMC_URL="https://api.papermc.io/v2/projects/paper/versions/${LATEST_VERSION}/builds/${LATEST_BUILD}/downloads/${JAR_NAME}" the url is hardcoded to the paper project.

This is a slightly modified version of the script that does support all projects and does not hard code any projects into the script

#!/bin/bash

PROJECT="paper"
MINECRAFT_VERSION="1.20.4"

LATEST_VERSION=$(curl -s https://api.papermc.io/v2/projects/${PROJECT} | \
    jq -r '.versions[-1]')

LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds | \
    jq -r '.builds | map(select(.channel == "default") | .build) | .[-1]')

JAR_NAME=${PROJECT}-${LATEST_VERSION}-${LATEST_BUILD}.jar

PAPERMC_URL="https://api.papermc.io/v2/projects/${PROJECT}/versions/${LATEST_VERSION}/builds/${LATEST_BUILD}/downloads/${JAR_NAME}"

# Download the latest PaperMC version
curl -o server.jar $PAPERMC_URL
echo "Downloads completed"

https://docs.papermc.io/velocity/dev/creating-your-first-plugin, quotes that 3.1.1 is the newest version, but 3.2.0 is the newest version. Please replace 3.1.1 with 3.2.0-SNAPSHOT.

I hope this is the right place to address this issue.

Thx

I have a datapack that allows for smithing templates to be applied to tools. With specifically Paper (I am on 1.20.1-69) the NBT data is semi-randomly cleared.

Steps I took to replicate:

• booted fresh 1.20.1-69 server on local
• installed datapack to allow for tools to have armor trim applied (nothing else, no plugins, no config changes, etc)
• restarted server
• gave myself op, changed gamemode to creative, gave myself needed items for recipe
• apply template to tool
• quickly randomly move tool around inventory/rapidly click on it (if its slow enough it doesnt seem to happen)
• NBT data for trim is lost.

Notes:

• I was not able to replicate this on a vanilla local server, or singleplayer
• I also tested it in survival and experienced the same NBT data loss
• all tests were done with a vanilla client (resource packs only)
• other NBT data (for enchants, names, etc) is not lost

Attached (redacted) log and datapack.
dp-trimmable-tools-mc1.20-v1.0.4.zip
latest.log

Since the CONTRIBUTING.md file in the Paper repository is the main source for information on contributing i think referencing or featuring it in the docs would be a good idea.

This configuration section was removed somewhere in the middle of 1.19-1.19.2, I believe here PaperMC/Paper@01a1387

And the new one was introduced:

chunk-system:
  gen-parallelism: default # what are other options?
  io-threads: -1 # does it affect load&save chunk operations?
  worker-threads: -1 # what does one worker do?

Been meaning to create an issue for this for a while, people with write access here are asked to maybe clean up this issue and maybe create sub-issues, etc; There has been a few small talks about this internally but I feel that a more public/documentated discussion would be ideal and maybe aid in finding help to accomplish this

A key aspect of our documentation is that we still heavily rely on the documentation elsewhere, e.g. the bukkit wiki, the spigot wiki, for a large part of our documentation

While this has worked well in the past, it leaves a lot of stuff lacking or missing, ref: #20 and #22 for example, especially post hard fork, we are going to need to consider the duplication of this documentation in order to offer a more central replacement

A few key examples are, as above, commands.yml, but, also, changes to spigot.yml, added permissions, etc, as well as many pieces of documentation such as the firewall guide on spigot which offers flawed recommendations for plugins. A big thing is that I question if we'd be really better off moving towards a real wiki for this, given that it's more accessible for people who aren't developers vs working with the niche restructured text format.

hard fork plans do offer some concerns to the existing documentation and our reliance of info elsewhere, e.g. hardforking gives us the chance to heavily re-organise the configuration layout for a well needed clean up and organisation, which does put some questions around documentation there, especially as I feel that the current layout of the config docs is somewhat unwieldy at times

I also feel that the current layout of documentation isn't exactly ideal, I've done a bit of work on this on the past, but, expanding on the documentation as is feels a bit icky due to the current layout, I've wanted to do more on this but this would impact existing PRs of which my involvement with this repo is somewhat limited for various reasons (health, time, more productive working on code...)

I think a public discussion on this would likely be ideal as we can determine a goal for this or at least discuss plans going forward, does a real wiki (with limited registration for spam/quality reasons) make a much better sense long term?

1-2 simple examples of getting builds of a version or something on https://docs.papermc.io/misc/downloads-api.

These would probably be more useful than the Swagger docs

The commands.yml file is already well documented here. However, Paper has added a very useful $sender placeholder for aliases to get the name of the command sender. This should be documented somewhere.

The Agolia Crawler currently only allows you to navigate to the page a particular search result is on when it is a node within the Configuration component. This should allow you to navigate correctly by setting the url tag properly.

return helpers.docsearch({
  recordProps: {
    lvl0: {
      selectors: "",
      defaultValue: lvl0,
    },
    url: {
      selectors: "",
      defaultValue: url.toString(),
    },
    lvl1: "h1",
    lvl2: "article h2",
    lvl3: "article h3",
    lvl4: "article h4",
    lvl5: "article h5, article td:first-child",
    lvl6: "article h6",
    content:
      "article p, article li, article td:last-child, article button.with-value",
  },
});

This is how you can override the URL tag, however, I do not know how to access the anchor tag for this item. You do have access to a Cheerio instance which might be possible to use, however I cannot think of anything currently.

Is it possible to disable the GUI option by default when Server Configuration uses Velocity Flags?

boom

Aside from Paper specific configuration and API, our documentation should also cover more basic information for both server owners and plugin developers. This issue covers the dev side of things:

After #145, there are more pages that should exist in the Component API category, diving into specific integrations between adventure and the paper api.

Paper exposes a number of system properties that aren't documented anywhere. Some of these are intentionally only exposed as system properties so that people do not use them- which of these do and do not get documented could be up for discussion.

I grabbed this quick list of what I believe to have been added by paper but I haven't checked this to be correct or verified it is contains all additions. Just leaving it here for myself/whoever wants to document these.

paper.playerconnection.keepalive
paper.ticklist-excessive-delay-threshold
timings.bypassMax
LetMeReload
paper.disableChannelLimit
net.kyori.adventure.text.warnWhenLegacyFormattingDetected
Paper.DisableClassPrioritization
Paper.disableFlushConsolidate
Paper.debugDynamicMissingKeys
disable.watchdog
paper.explicit-flush
paper.debug-async-visible-chunks
Paper.enable-sync-chunk-writes
paper.debug-sync-loads
Paper.ignoreWorldDataVersion
Paper.allowAsyncChunksSingleCore
debug.entities
Paper.bypassHostCheck
paper.ticklist-warn-on-excessive-delay
debug.rewriteForIde
convertLegacySigns
Paper.IgnoreJavaVersion
paper.waitforchunks
paper.flush-on-save
disable.book-limits
paper.alwaysPrintWarningState
paper.maxCustomChannelName
Paper.maxSignLength
Paper.FilterThreshhold
Paper.minPrecachedDatafixVersion
paper.maxChunkThreads
Paper.nibbleBucketSize
Paper.maxNibblePoolSize
Paper.WorkerThreadCount
Paper.excessiveTELimit
paper.ticklist-max-tick-delay
printSaveStats
paper.maxChunkThreads
paper.genThreadPriority
paper.loadThreadPriority

Bamboo minimum grow height value is not listed under the bamboo list item

The current paper plugin docs are somewhat outdated when compared to the current state. These need updating at some point.

Material javadoc isn't really user friendly, including the fact that it still has legacy materials which confuses new people

This would be a good addition to https://docs.papermc.io/paper/cat/admin/reference

The general idea is to make an alternative solution which is more user friendly than something made as a code documentation

My idea on how this could be done is a table

• The table has a mode at the top where the user can select between "all materials", "items" and "blocks". The selection should reflect in the link so it could be easily shareable, should be useful for plugin developers to share in documentation for users with a preselected link. This is to prevent people from accidentally putting POTATOES instead of POTATO in a list of items in configs
• The ability to filter materials based on vanilla tags
• Columns which aren't appropriate with the mode are hidden (like item meta for block mode)
• It would be good to have those columns
  • Material name, as in https://jd.papermc.io/paper/1.20/org/bukkit/Material.html
  • Namespaced name, from https://jd.papermc.io/paper/1.20/org/bukkit/Registry.html#MATERIAL (and how are they in nms registry and in any vanilla command)
  • BlockData class
  • BlockState class
  • ItemMeta class
  • Translatable key
  • List of tags this material is part of

Of course this is just a suggestion and anything would be better than java docs

Many entries are missing descriptions from the crawler

Similar to https://docs.papermc.io/velocity/built-in-commands

Todo: add Todo list with commands that need documentating

It seems that developers see it pretty hard to use the mob goal api, there should be a guide on how to use classes like
https://jd.papermc.io/paper/1.20/com/destroystokyo/paper/entity/ai/MobGoals.html
https://jd.papermc.io/paper/1.20/com/destroystokyo/paper/entity/ai/Goal.html

The javadocs aren't really great and there are no tutorials

This is a request to list all (major) changes PaperMC makes to gameplay on top of Spigot (i.e. that players would notice versus a vanilla server or that break adventure maps/farms made for vanilla servers) that are enabled by default.
I have looked through the docs and while these are listed in the configuration page, it would be very, very helpful to have these listed separately, for example, on the FAQ page (https://paper.readthedocs.io/en/latest/about/faq.html).

This way, instead of looking though the configuration docs/file and figuring out if each setting should be true or false (basically having to read the all the config options and debate if they are different from the vanilla behaviour), it would be a simple glance at the FAQ to figure out which setting(s) to change.

Not only would this benefit first-time setup, but it would also benefit in the case people (like many) have not updated in a while and notice a new build of PaperMC made a gameplay change so they now have to go through several (possibly lots of) commit messages to track down what has changed.
In fact, this issue was prompted by the "Don't apply cramming damage to players" patch (PaperMC/Paper#5903) which changes gameplay by default but can be hard to notice, especially as time passes and this build/commit message is not displayed on the downloads page anymore.

A list of the changes I can think of that should be listed:

• The various fixed duplication glitches
• Disabled breaking unbreakable blocks (+headless pistons)
• save-empty-scoreboard-teams
• use-vanilla-world-scoreboard-name-coloring
• allow-non-player-entities-on-scoreboards
• iron-golems-can-spawn-in-air
• disable-unloaded-chunk-enderpearl-exploit
• fix-curing-zombie-villager-discount-exploit
• fix-invulnerable-end-crystal-exploit
• allow-player-cramming-damage

Note that the above list is probably incomplete because (and this illustrates my point) I am not 100% sure if any of the other settings can impact gameplay/break some adventure maps/farms.
Also, just to be clear, I am not asking for any of these settings to be removed/changed back to the setting that would match vanilla by default, but to simply point them out in a single location (the FAQ page).

This would also help clear up the confusion that some people have which sometimes leads to server owners choosing Spigot because "Paper changes vanilla too much" but they are not sure exactly what or what setting to change.

TL;DR - please list all the (major) changes PaperMC makes to vanilla with the default configuration in the FAQ.

It would be good if the docs would include information for people that want to start developing plugins against the paper-api. Things that it should (imo) include:

• Maven/gradle info as well as common IDE setup information (e.g. Minecraft Development IntelliJ plugin)
• Links to general plugin documentation on the Bukkit and Spigot wikis
• Information regarding changed/added API and libraries (e.g. adventure). Ideally this would be pretty detailed but just having a general overview (e.g. important events and api groups like pre spawn and player profile) should be a big help for the start

A guide to creating and handling custom enchantments, but not using the traditionally hacky way, instead using the PDC and ItemStack lore as a way to handle custom enchants. This is to discourage bad use of the "API". Should probably include a simple way to add the enchantment to the itemstack, probably by listening to the enchant event, and a way to detect the itemstack was used for something.

Was initially part of #107 but was split off to be its own guide.