feat: add support for vanilla-like experience in PaperMC server configuration

[Lenart12]

This PR adds an optional enviroment flag PAPER_VANILLA_LIKE: true which will apply recommended settings for Vanilla-like experience on Paper servers based on this article: https://docs.papermc.io/paper/vanilla/

[Copilot]

Pull request overview

This PR adds support for configuring PaperMC servers with a vanilla-like experience through a new PAPER_VANILLA_LIKE environment variable. When enabled, it automatically applies configuration settings recommended by PaperMC's official guide to minimize Paper-specific optimizations and changes that differ from vanilla Minecraft gameplay.

Changes:

• Added PAPER_VANILLA_LIKE environment variable that applies vanilla-like configuration patches to Paper servers (1.19+)
• Implemented comprehensive patch definitions covering paper-global.yml, paper-world-defaults.yml, and spigot.yml
• Added documentation, examples, and test coverage for the new feature

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scripts/start-deployPaper	Adds logic to enable vanilla-like patches when PAPER_VANILLA_LIKE=true, validates Minecraft version is 1.19+, and sets PAUSE_WHEN_EMPTY_SECONDS to 60 by default
scripts/start-setupEnvVariables	Applies the vanilla-like patches before user-provided PATCH_DEFINITIONS when APPLY_PAPER_VANILLA_LIKE_PATCHES is set
files/paper-vanilla-like-patches.json	Comprehensive JSON patch definitions applying vanilla-like configuration values across Paper and Spigot config files
docs/types-and-platforms/server-types/paper.md	User-facing documentation explaining the PAPER_VANILLA_LIKE feature with usage examples and important notes
examples/paper-vanilla-like/compose.yml	Example Docker Compose file demonstrating how to use the vanilla-like configuration
tests/setuponlytests/paper_vanilla_like/docker-compose.yml	Test setup configuration for the vanilla-like feature
tests/setuponlytests/paper_vanilla_like/verify.sh	Test verification script that validates the patches are correctly applied

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Lenart12]

Seems like also 1.20.x config fails to patch. I only tested this working for 1.21.x. I'm not sure what would be the best way to handle all the different versions.

[itzg]

Thanks for submitting this PR. Would be great to start with an issue next time so that the idea can be discussed first.

Seems like also 1.20.x config fails to patch. I only tested this working for 1.21.x. I'm not sure what would be the best way to handle all the different versions.

Yes, that's the big challenge with maintaining this image.

I haven't reviewed the changes, but I'm worried about how many files were touched. 7 files and over 400 lines added?

Perhaps this is something best left for the end user to configure themselves. And I don't want to have to forever maintain adjustments that Paper publishes.

[Lenart12]

Actual implementation only touches 2 files. The rest is docs+tests and a file large file that contains all the patches. So in reality there is little extra code to maintain.

If this does not get accepted I have also though about an easier patching method. Something that could be enviroment only...
maybe something like:

environment:
  PATCH_config__paper-global.yml: |
    $.some.path: foo
    $.some.other.path: 3

Then everything could be self contained inside docker compose.

[itzg]

Actual implementation only touches 2 files. The rest is docs+tests and a file large file that contains all the patches. So in reality there is little extra code to maintain.

Sorry I jumped to conclusions. I haven't had a chance to jump a computer to look closer.

Regarding the PATCH_config__paper-global.yml suggestion...that seems cool but a bit cryptic. I understand the motivation since there's only so much that can be conveyed in a key-value environment variable.

It seems like inline configs mounted into the container would be more robust and leverage the existing patch mechanism

https://docs.docker.com/reference/compose-file/configs/#example-3

[itzg]

Now that I actually looked at the changes, I'm fine with the overall idea. Please try to incorporate my suggestion though.

[itzg]

I'd prefer this to be more generic like EXTRA_PATCHES. It could be a patch files and the vanilla paper logic can simply add to that variable. That also allows for users to extend their own way too.

[Lenart12]

Good idea :^)

[itzg]

This is the next change you're planning on, right?

[Lenart12]

I thought about what you said about the difficulty of maintaining all the patches and backwards compatibility... Maybe I would rather have my proposed patching method from environment variables and just add a recommended patch for the latest version to the docs instead.

[itzg]

Ultimately this is my project that I have to maintain and endorse. Please proceed with just the current approach with variable rename. I later realized that is what I feel comfortable maintaining and apologize for commenting prematurely otherwise.

[itzg]

...but to what you're saying, yes could supply the patch file as a documentation section showing how to translate PaperMC's guidance.

[Lenart12]

The idea does not seem so cryptic to me. I know about inline configs and I just feel like the docker compose would grow a lot writing json patch schema by hand. I had it envisioned it like this because it would allow for a compact representation of the patch files. The format would be like:

Define an environment variable in the format PATCH_ with the slashes replaced with double underscores, e.g. config/paper-global.yml becomes PATCH_config__paper-global.yml (and x underscores (x > 2) mean x-1 underscores inside the path to keep full compatibility).

The contents of the variable would be simple line by line instructions to generate a 1:1 translation in to a patch file.

For $set:
$.chunks.delay-chunk-unloads-by = 0s | int (value type can be optional and defaults to auto)
For $put:
$.entities.spawning:max-arrow-despawn-invulnerability = disabled
For $add:
$.unsupported-settings.oversized-item-component-sanitizer.dont_sanitize[] = minecraft:container