├── .editorconfig ├── .github ├── actions │ └── setup-node-pnpm │ │ └── action.yml └── workflows │ ├── build-preview.yaml │ ├── deploy-preview.yaml │ ├── deploy.yaml │ ├── format.yaml │ └── spellcheck.yaml ├── .gitignore ├── .prettierignore ├── .prettierrc.json ├── .typos.toml ├── .vscode ├── extensions.json └── launch.json ├── CONTRIBUTING.md ├── LICENSE ├── LICENSE-docs ├── README.md ├── _headers ├── _redirects ├── astro.config.ts ├── package.json ├── patches └── @astrojs__starlight@0.34.3.patch ├── pnpm-lock.yaml ├── pnpm-workspace.yaml ├── public ├── d2 │ └── docs │ │ ├── paper │ │ └── dev │ │ │ ├── api │ │ │ ├── command-api │ │ │ │ └── basics │ │ │ │ │ ├── command-tree-0.svg │ │ │ │ │ ├── command-tree-1.svg │ │ │ │ │ ├── command-tree-2.svg │ │ │ │ │ ├── command-tree-3.svg │ │ │ │ │ ├── command-tree-4.svg │ │ │ │ │ ├── command-tree-5.svg │ │ │ │ │ └── command-tree-6.svg │ │ │ └── entity-api │ │ │ │ └── display-entities-0.svg │ │ │ └── getting-started │ │ │ ├── paper-plugins-0.svg │ │ │ └── plugin-yml-0.svg │ │ └── velocity │ │ └── dev │ │ └── api │ │ ├── plugin-messaging-0.svg │ │ ├── plugin-messaging-1.svg │ │ ├── plugin-messaging-2.svg │ │ ├── plugin-messaging-3.svg │ │ └── plugin-messaging-4.svg └── manifest.json ├── src ├── components │ ├── ConfigNode.astro │ ├── LinkCard.astro │ ├── PageCards.astro │ ├── Version.astro │ ├── Video.astro │ ├── overrides │ │ ├── Banner.astro │ │ ├── Footer.astro │ │ ├── Head.astro │ │ ├── LastUpdated.astro │ │ ├── MobileTableOfContents.astro │ │ ├── PageFrame.astro │ │ ├── SiteTitle.astro │ │ ├── SocialIcons.astro │ │ └── TableOfContents.astro │ └── tools │ │ ├── ItemCommandConverter.svelte │ │ └── StartScriptGenerator.svelte ├── config │ ├── paper │ │ ├── banned-ips-single.yml │ │ ├── banned-players-single.yml │ │ ├── bukkit.yml │ │ ├── commands.yml │ │ ├── eula.yml │ │ ├── help.yml │ │ ├── ops-single.yml │ │ ├── paper-global.yml │ │ ├── paper-world-defaults.yml │ │ ├── permissions.yml │ │ ├── server-properties.yml │ │ ├── spigot.yml │ │ └── whitelist-single.yml │ └── waterfall │ │ └── waterfall-config.yml ├── content.config.ts ├── content │ └── docs │ │ ├── folia │ │ ├── admin │ │ │ ├── index.mdx │ │ │ └── reference │ │ │ │ ├── faq.md │ │ │ │ ├── index.mdx │ │ │ │ ├── overview.md │ │ │ │ └── region-logic.md │ │ └── index.mdx │ │ ├── index.mdx │ │ ├── misc │ │ ├── assets.md │ │ ├── assets │ │ │ ├── github-secrets-actions.png │ │ │ ├── hangar-create-snapshot-channel.png │ │ │ ├── pterodactyl-manual.png │ │ │ └── pterodactyl-prompt.png │ │ ├── contact.md │ │ ├── downloads-api.mdx │ │ ├── hangar-publishing.md │ │ ├── index.mdx │ │ ├── java-install.md │ │ └── tools │ │ │ ├── assets │ │ │ └── adventure-webui.png │ │ │ ├── diff-viewer.md │ │ │ ├── index.mdx │ │ │ ├── item-command-converter.mdx │ │ │ ├── minimessage-web-editor.md │ │ │ └── start-script-gen.mdx │ │ ├── paper │ │ ├── admin │ │ │ ├── getting-started │ │ │ │ ├── adding-plugins.md │ │ │ │ ├── assets │ │ │ │ │ └── hangar.png │ │ │ │ ├── getting-started.mdx │ │ │ │ ├── index.mdx │ │ │ │ ├── migration.md │ │ │ │ └── next-steps.md │ │ │ ├── how-to │ │ │ │ ├── aikars-flags.md │ │ │ │ ├── anti-xray.mdx │ │ │ │ ├── assets │ │ │ │ │ ├── anti-xray-nether.png │ │ │ │ │ └── anti-xray-overworld.png │ │ │ │ ├── basic-troubleshooting.mdx │ │ │ │ ├── index.mdx │ │ │ │ ├── profiling.md │ │ │ │ ├── update.md │ │ │ │ └── vanilla.mdx │ │ │ ├── index.mdx │ │ │ ├── misc │ │ │ │ ├── faq.md │ │ │ │ ├── index.mdx │ │ │ │ └── paper-bug-fixes.md │ │ │ └── reference │ │ │ │ ├── assets │ │ │ │ └── plugin-list.png │ │ │ │ ├── configuration │ │ │ │ ├── bukkit-commands-configuration.mdx │ │ │ │ ├── bukkit-configuration.mdx │ │ │ │ ├── bukkit-help-configuration.mdx │ │ │ │ ├── bukkit-permissions-configuration.mdx │ │ │ │ ├── global-configuration.mdx │ │ │ │ ├── index.mdx │ │ │ │ ├── server-properties.mdx │ │ │ │ ├── spigot-configuration.mdx │ │ │ │ ├── vanilla-data-files.mdx │ │ │ │ └── world-configuration.mdx │ │ │ │ ├── index.mdx │ │ │ │ ├── paper-plugins.md │ │ │ │ ├── system-properties.md │ │ │ │ └── vanilla-command-permissions.md │ │ ├── contributing │ │ │ ├── events.md │ │ │ └── index.mdx │ │ ├── dev │ │ │ ├── api │ │ │ │ ├── assets │ │ │ │ │ └── data-component-api-tree.png │ │ │ │ ├── command-api │ │ │ │ │ ├── arguments │ │ │ │ │ │ ├── adventure.mdx │ │ │ │ │ │ ├── assets │ │ │ │ │ │ │ ├── registry-arguments │ │ │ │ │ │ │ │ ├── enchants-registry.mp4 │ │ │ │ │ │ │ │ ├── resource-attributes.mp4 │ │ │ │ │ │ │ │ ├── resource-banner-pattern.mp4 │ │ │ │ │ │ │ │ ├── resource-biome.mp4 │ │ │ │ │ │ │ │ ├── resource-block.mp4 │ │ │ │ │ │ │ │ ├── resource-cat-variant.mp4 │ │ │ │ │ │ │ │ ├── resource-chicken-variant.mp4 │ │ │ │ │ │ │ │ ├── resource-cow-variant.mp4 │ │ │ │ │ │ │ │ ├── resource-damage-type.mp4 │ │ │ │ │ │ │ │ ├── resource-data-component-type.mp4 │ │ │ │ │ │ │ │ ├── resource-enchantment.mp4 │ │ │ │ │ │ │ │ ├── resource-entity-type.mp4 │ │ │ │ │ │ │ │ ├── resource-fluid.mp4 │ │ │ │ │ │ │ │ ├── resource-frog-variant.mp4 │ │ │ │ │ │ │ │ ├── resource-game-event.mp4 │ │ │ │ │ │ │ │ ├── resource-instrument.mp4 │ │ │ │ │ │ │ │ ├── resource-item.mp4 │ │ │ │ │ │ │ │ ├── resource-jukebox-song.mp4 │ │ │ │ │ │ │ │ ├── resource-map-decoration-type.mp4 │ │ │ │ │ │ │ │ ├── resource-memory-module-type.mp4 │ │ │ │ │ │ │ │ ├── resource-menu.mp4 │ │ │ │ │ │ │ │ ├── resource-mob-effect.mp4 │ │ │ │ │ │ │ │ ├── resource-painting-variant.mp4 │ │ │ │ │ │ │ │ ├── resource-particle-type.mp4 │ │ │ │ │ │ │ │ ├── resource-pig-variant.mp4 │ │ │ │ │ │ │ │ ├── resource-potion.mp4 │ │ │ │ │ │ │ │ ├── resource-sound-event.mp4 │ │ │ │ │ │ │ │ ├── resource-structure-type.mp4 │ │ │ │ │ │ │ │ ├── resource-trim-material.mp4 │ │ │ │ │ │ │ │ ├── resource-trim-pattern.mp4 │ │ │ │ │ │ │ │ ├── resource-villager-profession.mp4 │ │ │ │ │ │ │ │ ├── resource-villager-type.mp4 │ │ │ │ │ │ │ │ ├── resource-wolf-sound-variant.mp4 │ │ │ │ │ │ │ │ ├── resource-wolf-variant.mp4 │ │ │ │ │ │ │ │ └── resourcekey-item.mp4 │ │ │ │ │ │ │ └── vanilla-arguments │ │ │ │ │ │ │ │ ├── blockposition.mp4 │ │ │ │ │ │ │ │ ├── blockstate.mp4 │ │ │ │ │ │ │ │ ├── component.mp4 │ │ │ │ │ │ │ │ ├── doublerange.mp4 │ │ │ │ │ │ │ │ ├── entities.mp4 │ │ │ │ │ │ │ │ ├── entity-opped.mp4 │ │ │ │ │ │ │ │ ├── entity-unopped.mp4 │ │ │ │ │ │ │ │ ├── entityanchor.mp4 │ │ │ │ │ │ │ │ ├── fineposition.mp4 │ │ │ │ │ │ │ │ ├── gamemode.mp4 │ │ │ │ │ │ │ │ ├── heightmap.mp4 │ │ │ │ │ │ │ │ ├── integerrange.mp4 │ │ │ │ │ │ │ │ ├── itempredicate.mp4 │ │ │ │ │ │ │ │ ├── itemstack.mp4 │ │ │ │ │ │ │ │ ├── key.mp4 │ │ │ │ │ │ │ │ ├── namedcolor.mp4 │ │ │ │ │ │ │ │ ├── namespacedkey.mp4 │ │ │ │ │ │ │ │ ├── objectivecriteria.mp4 │ │ │ │ │ │ │ │ ├── player.mp4 │ │ │ │ │ │ │ │ ├── playerprofiles.mp4 │ │ │ │ │ │ │ │ ├── players.mp4 │ │ │ │ │ │ │ │ ├── scoreboarddisplayslot.mp4 │ │ │ │ │ │ │ │ ├── signedmessage.mp4 │ │ │ │ │ │ │ │ ├── style.mp4 │ │ │ │ │ │ │ │ ├── templatemirror.mp4 │ │ │ │ │ │ │ │ ├── templaterotation.mp4 │ │ │ │ │ │ │ │ ├── time.mp4 │ │ │ │ │ │ │ │ ├── uuid.mp4 │ │ │ │ │ │ │ │ └── world.mp4 │ │ │ │ │ │ ├── entity-player.mdx │ │ │ │ │ │ ├── enums.mdx │ │ │ │ │ │ ├── index.mdx │ │ │ │ │ │ ├── location.mdx │ │ │ │ │ │ ├── minecraft.md │ │ │ │ │ │ ├── paper.mdx │ │ │ │ │ │ ├── predicate.mdx │ │ │ │ │ │ └── registry.mdx │ │ │ │ │ ├── basics │ │ │ │ │ │ ├── argument-suggestions.mdx │ │ │ │ │ │ ├── arguments-and-literals.md │ │ │ │ │ │ ├── assets │ │ │ │ │ │ │ ├── big-float.png │ │ │ │ │ │ │ ├── client-server-mismatch.png │ │ │ │ │ │ │ ├── flyspeed-console.png │ │ │ │ │ │ │ ├── flyspeed-player.png │ │ │ │ │ │ │ ├── flyspeed-proxied.png │ │ │ │ │ │ │ ├── forest │ │ │ │ │ │ │ │ ├── tree-descriptions.png │ │ │ │ │ │ │ │ └── tree.png │ │ │ │ │ │ │ ├── give-item-command.mp4 │ │ │ │ │ │ │ ├── ice-cream-invalid.png │ │ │ │ │ │ │ ├── ice-cream.png │ │ │ │ │ │ │ ├── select-name-command.mp4 │ │ │ │ │ │ │ ├── small-float.png │ │ │ │ │ │ │ ├── string-arguments.gif │ │ │ │ │ │ │ ├── suggestion-tooltip.png │ │ │ │ │ │ │ └── valid-float.png │ │ │ │ │ │ ├── command-tree.mdx │ │ │ │ │ │ ├── custom-arguments.md │ │ │ │ │ │ ├── executors.md │ │ │ │ │ │ ├── index.mdx │ │ │ │ │ │ ├── introduction.md │ │ │ │ │ │ ├── registration.md │ │ │ │ │ │ └── requirements.md │ │ │ │ │ ├── index.mdx │ │ │ │ │ └── misc │ │ │ │ │ │ ├── assets │ │ │ │ │ │ ├── broadcast-command.png │ │ │ │ │ │ ├── broadcast-suggestions-finished.png │ │ │ │ │ │ ├── broadcast-suggestions-none.png │ │ │ │ │ │ ├── broadcast-suggestions-unfinished.png │ │ │ │ │ │ ├── bukkitparty-command.png │ │ │ │ │ │ └── paperparty-command.png │ │ │ │ │ │ ├── basic-command.md │ │ │ │ │ │ ├── comparison-bukkit-brigadier.md │ │ │ │ │ │ └── index.mdx │ │ │ │ ├── component-api │ │ │ │ │ ├── audiences.md │ │ │ │ │ ├── i18n.md │ │ │ │ │ ├── index.mdx │ │ │ │ │ └── intro.md │ │ │ │ ├── custom-inventory-holder.md │ │ │ │ ├── data-component-api.md │ │ │ │ ├── entity-api │ │ │ │ │ ├── assets │ │ │ │ │ │ ├── display-interp.gif │ │ │ │ │ │ ├── display-rotation.png │ │ │ │ │ │ ├── display-scale.png │ │ │ │ │ │ └── display-trans.png │ │ │ │ │ ├── display-entities.md │ │ │ │ │ ├── entity-teleport.md │ │ │ │ │ └── index.mdx │ │ │ │ ├── event-api │ │ │ │ │ ├── assets │ │ │ │ │ │ ├── plain-message-rendering.png │ │ │ │ │ │ └── prefix-rendering.png │ │ │ │ │ ├── chat-event.md │ │ │ │ │ ├── custom-events.md │ │ │ │ │ ├── event-listeners.md │ │ │ │ │ ├── handler-lists.md │ │ │ │ │ └── index.mdx │ │ │ │ ├── folia-support.md │ │ │ │ ├── index.mdx │ │ │ │ ├── lifecycle.md │ │ │ │ ├── pdc.md │ │ │ │ ├── plugin-configs.mdx │ │ │ │ ├── plugin-messaging.md │ │ │ │ ├── recipes.md │ │ │ │ ├── registries.md │ │ │ │ ├── roadmap.md │ │ │ │ └── scheduler.md │ │ │ ├── getting-started │ │ │ │ ├── assets │ │ │ │ │ ├── installing-plugin.png │ │ │ │ │ ├── new-project-paper.png │ │ │ │ │ ├── paper-plugin-overview.png │ │ │ │ │ └── restart-ide.png │ │ │ │ ├── how-do-plugins-work.md │ │ │ │ ├── index.mdx │ │ │ │ ├── paper-plugins.md │ │ │ │ ├── plugin-yml.mdx │ │ │ │ ├── project-setup.mdx │ │ │ │ └── userdev.md │ │ │ ├── index.mdx │ │ │ └── misc │ │ │ │ ├── assets │ │ │ │ ├── add_breakpoints.png │ │ │ │ ├── config_add.png │ │ │ │ ├── config_dropdown.png │ │ │ │ ├── debugger_connect.png │ │ │ │ └── debugger_use.png │ │ │ │ ├── databases.md │ │ │ │ ├── debugging.md │ │ │ │ ├── index.mdx │ │ │ │ ├── internal-code.md │ │ │ │ └── reading-stacktraces.md │ │ └── index.mdx │ │ ├── velocity │ │ ├── admin │ │ │ ├── getting-started │ │ │ │ ├── faq.md │ │ │ │ ├── forwarding.md │ │ │ │ ├── getting-started.md │ │ │ │ ├── index.mdx │ │ │ │ └── why-velocity.md │ │ │ ├── how-to │ │ │ │ ├── index.mdx │ │ │ │ ├── migration.md │ │ │ │ ├── security.md │ │ │ │ └── tuning.md │ │ │ ├── index.mdx │ │ │ └── reference │ │ │ │ ├── commands.md │ │ │ │ ├── comparison.md │ │ │ │ ├── configuration.md │ │ │ │ ├── index.mdx │ │ │ │ ├── libraries.md │ │ │ │ ├── server-compatibility.mdx │ │ │ │ └── system-properties.md │ │ ├── dev │ │ │ ├── api │ │ │ │ ├── command.md │ │ │ │ ├── event.md │ │ │ │ ├── index.mdx │ │ │ │ ├── plugin-messaging.md │ │ │ │ └── scheduler.md │ │ │ ├── getting-started │ │ │ │ ├── api-basics.md │ │ │ │ ├── assets │ │ │ │ │ ├── installing-plugin.png │ │ │ │ │ ├── new-project-velocity.png │ │ │ │ │ ├── restart-ide.png │ │ │ │ │ └── velocity-plugin-overview.png │ │ │ │ ├── creating-your-first-plugin.mdx │ │ │ │ ├── index.mdx │ │ │ │ └── pitfalls.md │ │ │ ├── how-to │ │ │ │ ├── dependencies.md │ │ │ │ ├── index.mdx │ │ │ │ └── porting-from-velocity-1.md │ │ │ └── index.mdx │ │ └── index.mdx │ │ └── waterfall │ │ ├── configuration.mdx │ │ ├── getting-started.md │ │ └── index.mdx ├── env.d.ts ├── pages │ └── robots.txt.ts ├── styles │ └── custom.css └── utils │ ├── config.ts │ ├── git.ts │ ├── markdown.ts │ ├── remark │ ├── code_const.ts │ └── javadoc.ts │ ├── sidebar.ts │ └── versions.ts ├── svelte.config.ts └── tsconfig.json /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | charset = utf-8 5 | end_of_line = lf 6 | indent_style = space 7 | indent_size = 2 8 | max_line_length = 120 9 | insert_final_newline = true 10 | trim_trailing_whitespace = true 11 | -------------------------------------------------------------------------------- /.github/actions/setup-node-pnpm/action.yml: -------------------------------------------------------------------------------- 1 | name: setup-node-pnpm 2 | description: Setup Node and PNPM 3 | runs: 4 | using: "composite" 5 | steps: 6 | - name: "setup pnpm" 7 | uses: "pnpm/action-setup@v4" 8 | - name: "setup node" 9 | uses: "actions/setup-node@v4" 10 | with: 11 | cache: "pnpm" 12 | node-version: 22 13 | -------------------------------------------------------------------------------- /.github/workflows/build-preview.yaml: -------------------------------------------------------------------------------- 1 | name: "Build Preview Deployment" 2 | 3 | on: 4 | pull_request: 5 | types: [opened, synchronize] 6 | 7 | jobs: 8 | build-preview: 9 | runs-on: "ubuntu-latest" 10 | name: "Build Preview Site and Upload Build Artifact" 11 | steps: 12 | - name: "checkout" 13 | uses: "actions/checkout@v4" 14 | with: 15 | fetch-depth: 0 16 | ref: ${{ github.event.pull_request.head.ref }} 17 | repository: ${{ github.event.pull_request.head.repo.full_name }} 18 | - name: "setup node and pnpm" 19 | uses: ./.github/actions/setup-node-pnpm 20 | - name: "setup d2" 21 | run: "curl -fsSL https://d2lang.com/install.sh | sh -s --" 22 | - name: "install dependencies" 23 | run: "pnpm install" 24 | - name: "build" 25 | run: "pnpm build" 26 | env: 27 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 28 | - name: "copy cloudflare configuration files to build directory" 29 | run: | 30 | cp _headers dist/ 31 | cp _redirects dist/ 32 | - name: "upload build artifact" 33 | uses: "actions/upload-artifact@v4" 34 | with: 35 | name: "preview-build" 36 | path: "dist" 37 | -------------------------------------------------------------------------------- /.github/workflows/deploy-preview.yaml: -------------------------------------------------------------------------------- 1 | name: "Publish Preview Deployment" 2 | 3 | on: 4 | workflow_run: 5 | workflows: ["Build Preview Deployment"] 6 | types: 7 | - completed 8 | 9 | permissions: 10 | actions: read 11 | contents: read 12 | deployments: write 13 | pull-requests: write 14 | 15 | jobs: 16 | deploy-preview: 17 | runs-on: "ubuntu-latest" 18 | if: ${{ github.event.workflow_run.conclusion == 'success' }} 19 | name: "Deploy Preview to Cloudflare Pages" 20 | steps: 21 | - name: "Download build artifact" 22 | uses: "actions/download-artifact@v4" 23 | id: "preview-build-artifact" 24 | with: 25 | name: "preview-build" 26 | path: "dist" 27 | github-token: ${{ secrets.GITHUB_TOKEN }} 28 | run-id: ${{ github.event.workflow_run.id }} 29 | - name: "Deploy to Cloudflare Pages" 30 | uses: "AdrianGonz97/refined-cf-pages-action@v1" 31 | with: 32 | apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} 33 | accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} 34 | githubToken: ${{ secrets.GITHUB_TOKEN }} 35 | projectName: "papermc-docs" 36 | deploymentName: "Preview" 37 | directory: ${{ steps.preview-build-artifact.outputs.download-path }} 38 | -------------------------------------------------------------------------------- /.github/workflows/deploy.yaml: -------------------------------------------------------------------------------- 1 | name: "Deploy to Cloudflare Pages (Production)" 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | deploy: 10 | runs-on: "ubuntu-latest" 11 | permissions: 12 | contents: read 13 | deployments: write 14 | pull-requests: write 15 | steps: 16 | - name: "checkout" 17 | uses: "actions/checkout@v4" 18 | with: 19 | fetch-depth: 0 20 | - name: "setup node and pnpm" 21 | uses: ./.github/actions/setup-node-pnpm 22 | - name: "setup d2" 23 | run: "curl -fsSL https://d2lang.com/install.sh | sh -s --" 24 | - name: "install dependencies" 25 | run: "pnpm install" 26 | - name: "build" 27 | run: "pnpm build" 28 | env: 29 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 30 | - name: "copy cloudflare configuration files to build directory" 31 | run: | 32 | cp _headers dist/ 33 | cp _redirects dist/ 34 | - name: "publish (push)" 35 | id: "cloudflare-publish" 36 | uses: "AdrianGonz97/refined-cf-pages-action@v1" 37 | with: 38 | apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} 39 | accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} 40 | projectName: "papermc-docs" 41 | deploymentName: "Production" 42 | directory: "dist" 43 | githubToken: ${{ secrets.GITHUB_TOKEN }} 44 | -------------------------------------------------------------------------------- /.github/workflows/format.yaml: -------------------------------------------------------------------------------- 1 | name: "Format check" 2 | 3 | on: 4 | - push 5 | - pull_request 6 | 7 | jobs: 8 | format: 9 | # run on all push events or on PR syncs not from the same repo 10 | if: github.event_name != 'pull_request' || github.repository != github.event.pull_request.head.repo.full_name 11 | 12 | runs-on: ubuntu-latest 13 | steps: 14 | - name: Checkout repository 15 | uses: actions/checkout@v4 16 | - name: "setup node and pnpm" 17 | uses: ./.github/actions/setup-node-pnpm 18 | - name: Install dependencies 19 | run: pnpm install 20 | - name: Check format 21 | run: pnpm format:check 22 | -------------------------------------------------------------------------------- /.github/workflows/spellcheck.yaml: -------------------------------------------------------------------------------- 1 | name: "Spell check" 2 | 3 | on: 4 | - push 5 | - pull_request 6 | 7 | jobs: 8 | check: 9 | # run on all push events or on PR syncs not from the same repo 10 | if: github.event_name != 'pull_request' || github.repository != github.event.pull_request.head.repo.full_name 11 | 12 | runs-on: ubuntu-latest 13 | steps: 14 | - name: Checkout repository 15 | uses: actions/checkout@v4 16 | - name: Spell check 17 | uses: crate-ci/typos@v1.32.0 18 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # build output 2 | dist/ 3 | # generated types 4 | .astro/ 5 | .cache/ 6 | 7 | # dependencies 8 | node_modules/ 9 | 10 | # logs 11 | npm-debug.log* 12 | yarn-debug.log* 13 | yarn-error.log* 14 | pnpm-debug.log* 15 | 16 | 17 | # environment variables 18 | .env 19 | .env.production 20 | 21 | # macOS-specific files 22 | .DS_Store 23 | 24 | .idea/ 25 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | pnpm-lock.yaml 2 | pnpm-workspace.yaml 3 | *.md 4 | *.mdx 5 | public/d2 6 | 7 | # Prettier has issues with Astro 8 | src/components/overrides/Head.astro 9 | src/components/ConfigNode.astro 10 | -------------------------------------------------------------------------------- /.prettierrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "arrowParens": "always", 3 | "singleQuote": false, 4 | "semi": true, 5 | "trailingComma": "es5", 6 | "plugins": ["prettier-plugin-astro", "prettier-plugin-svelte", "prettier-plugin-organize-imports"], 7 | "organizeImportsSkipDestructiveCodeActions": true, 8 | "overrides": [ 9 | { 10 | "files": "*.astro", 11 | "options": { 12 | "parser": "astro" 13 | } 14 | }, 15 | { 16 | "files": "*.svelte", 17 | "options": { 18 | "parser": "svelte" 19 | } 20 | } 21 | ] 22 | } 23 | -------------------------------------------------------------------------------- /.typos.toml: -------------------------------------------------------------------------------- 1 | [files] 2 | extend-exclude = [ 3 | "public/d2" # D2 output shouldn't be checked 4 | ] 5 | 6 | [default] 7 | locale = "en-us" 8 | extend-ignore-re = [ 9 | # {/* spellchecker: */} 10 | "(?s)\\{/\\*\\s*spellchecker:off\\s*\\*/\\}.*?\\n\\s*\\{/\\*\\s*spellchecker:on\\s*\\*/\\}" 11 | ] 12 | 13 | [default.extend-identifiers] 14 | Spectre = "Spectre" # ignore error, the vulnerability is named Spectre 15 | 16 | [default.extend-words] 17 | accessorise = "accessorize" 18 | aluminium = "aluminum" 19 | analyse = "analyze" 20 | armour = "armor" 21 | authorise = "authorize" 22 | authorised = "authorized" 23 | authorising = "authorizing" 24 | behaviour = "behavior" 25 | capitalise = "capitalize" 26 | catalogue = "catalog" 27 | centre = "center" 28 | civilisation = "civilization" 29 | civilised = "civilized" 30 | colour = "color" 31 | colours = "colors" 32 | defence = "defense" 33 | generalise = "generalize" 34 | generalised = "generalized" 35 | gramme = "gram" 36 | grammes = "grams" 37 | grey = "gray" 38 | honour = "honor" 39 | honours = "honors" 40 | initialise = "initialize" 41 | initialised = "initialized" 42 | initialiser = "initializer" 43 | kerb = "curb" 44 | kerbs = "curbs" 45 | labour = "labor" 46 | licence = "license" 47 | licences = "licenses" 48 | manoeuvre = "maneuver" 49 | manoeuvres = "maneuvers" 50 | metre = "meter" 51 | metres = "meters" 52 | modelled = "modeled" 53 | neighbour = "neighbor" 54 | neighbours = "neighbors" 55 | neighbouring = "neighboring" 56 | optimise = "optimize" 57 | optimised = "optimized" 58 | optimisation = "optimization" 59 | organisation = "organization" 60 | organise = "organize" 61 | organised = "organized" 62 | organising = "organizing" 63 | practise = "practice" 64 | practised = "practiced" 65 | practising = "practicing" 66 | recognise = "recognize" 67 | recognised = "recognized" 68 | recognising = "recognizing" 69 | routeing = "routing" 70 | serialise = "serialize" 71 | serialiser = "serializer" 72 | serialising = "serializing" 73 | deserialise = "deserialize" 74 | deserialiser = "deserializer" 75 | deserialising = "deserializing" 76 | tonne = "ton" 77 | tonnes = "tons" 78 | traveller = "traveler" 79 | travelling = "traveling" 80 | regionise = "regionize" 81 | regioniser = "regionizer" 82 | regionising = "regionizing" 83 | regionised = "regionized" 84 | 85 | # exceptions: 86 | 87 | # use British spelling to stay consistent with Bukkit 88 | canceled = "cancelled" 89 | canceling = "cancelling" 90 | cancelable = "cancellable" 91 | cancelation = "cancellation" 92 | -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | "recommendations": ["astro-build.astro-vscode"], 3 | "unwantedRecommendations": [] 4 | } 5 | -------------------------------------------------------------------------------- /.vscode/launch.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "0.2.0", 3 | "configurations": [ 4 | { 5 | "command": "./node_modules/.bin/astro dev", 6 | "name": "Development server", 7 | "request": "launch", 8 | "type": "node-terminal" 9 | } 10 | ] 11 | } 12 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 2-Clause License 2 | 3 | Copyright (c) PaperMC 4 | 5 | Redistribution and use in source and binary forms, with or without 6 | modification, are permitted provided that the following conditions are met: 7 | 8 | 1. Redistributions of source code must retain the above copyright notice, this 9 | list of conditions and the following disclaimer. 10 | 11 | 2. Redistributions in binary form must reproduce the above copyright notice, 12 | this list of conditions and the following disclaimer in the documentation 13 | and/or other materials provided with the distribution. 14 | 15 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 16 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 19 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 22 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 24 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # docs [![Discord](https://img.shields.io/discord/289587909051416579.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/papermc) ![Deployment Status](https://img.shields.io/github/deployments/PaperMC/docs/production?label=deployment&logo=github) ![License](https://img.shields.io/github/license/PaperMC/docs) 2 | 3 | This is the repository for all project documentation under the PaperMC umbrella. Content in this 4 | repository is published to [docs.papermc.io](https://docs.papermc.io) for viewing. 5 | 6 | ## Getting Started 7 | 8 | How to get docs running on your local machine for development. 9 | 10 | ### Prerequisites 11 | 12 | - [node 22](https://nodejs.org) 13 | - [pnpm](https://pnpm.io/installation) 14 | - [d2](https://d2lang.com/) (optional for development - used for generating diagrams) 15 | 16 | ### Local Development 17 | 18 | 1. Clone the repository. If you plan to make changes, create a fork first! 19 | 20 | ```bash 21 | $ git clone https://github.com/PaperMC/docs 22 | ``` 23 | 24 | 2. Install all required dependencies. 25 | 26 | ```bash 27 | $ pnpm install 28 | ``` 29 | 30 | 3. Start the development server. 31 | 32 | ```bash 33 | $ pnpm run dev 34 | ``` 35 | 36 | This will start a local development server and open a browser window. The majority of changes will 37 | be instantly reflected live without the need to restart the development server or reload the page in 38 | your browser. Edit away! 39 | 40 | ### Building 41 | 42 | ```bash 43 | $ pnpm run build 44 | ``` 45 | 46 | This command builds a production-ready deployment into the `build` directory. These files are ready 47 | to be hosted on any static content server. 48 | 49 | ## License 50 | 51 | The PaperMC Documentation (e.g., `.md` files in the `/src/content/docs` folder) is 52 | [CC-BY-SA-4.0](https://github.com/PaperMC/docs/blob/main/LICENSE-docs) licensed. 53 | 54 | The supporting code is 55 | [BSD-2-Clause](https://github.com/PaperMC/docs/blob/main/LICENSE) licensed. 56 | 57 | The PaperMC logomark is subject to its [own terms](https://docs.papermc.io/misc/assets) and does not 58 | inherit a license from any of the projects it represents. 59 | -------------------------------------------------------------------------------- /_headers: -------------------------------------------------------------------------------- 1 | /assets/(.*) 2 | cache-control: public, immutable, max-age=31536000 3 | -------------------------------------------------------------------------------- /_redirects: -------------------------------------------------------------------------------- 1 | /intro / 2 | /java-install-update /misc/java-install 3 | /papermc/* /misc/:splat 4 | /paper/1.18 /paper 5 | /paper/1.18/* /paper/:splat 6 | /paper/1.19 /paper 7 | /paper/1.19/* /paper/:splat 8 | /paper/1.20 /paper 9 | /paper/1.20/* /paper/:splat 10 | /velocity/developers/* /velocity/dev/:splat 11 | /velocity/dev/component-api/introduction /paper/dev/component-api/introduction 12 | /velocity/dev/component-api/i18n /paper/dev/component-api/i18n 13 | /velocity/dev/component-api/audiences /paper/dev/component-api/audiences 14 | /paper/reference/paper-per-world-configuration /paper/reference/world-configuration 15 | /paper/reference/paper-global-configuration /paper/reference/global-configuration 16 | /paper/per-world-configuration /paper/configuration 17 | /paper/configuration /paper/reference/configuration 18 | /paper/reference/vanilla-command-permissions /paper/reference/permissions 19 | /paper/dev/commands /paper/dev/command-api/basics/introduction 20 | /paper/dev/command-api/commands /paper/dev/command-api/basics/introduction 21 | /paper/dev/command-api/arguments /paper/dev/command-api/basics/arguments-and-literals 22 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "docs", 3 | "type": "module", 4 | "version": "0.0.0", 5 | "scripts": { 6 | "dev": "astro dev", 7 | "start": "astro dev", 8 | "build": "astro build", 9 | "preview": "astro preview", 10 | "astro": "astro", 11 | "format": "prettier . --write", 12 | "format:check": "prettier . --check" 13 | }, 14 | "dependencies": { 15 | "@astrojs/markdown-remark": "^6.3.1", 16 | "@astrojs/starlight": "^0.34.3", 17 | "@astrojs/svelte": "^7.0.13", 18 | "@fontsource/jetbrains-mono": "^5.2.5", 19 | "@fontsource/poppins": "^5.2.6", 20 | "astro": "^5.7.11", 21 | "astro-d2": "^0.7.0", 22 | "sharp": "^0.34.1", 23 | "starlight-contributor-list": "^0.3.0", 24 | "starlight-links-validator": "^0.16.0", 25 | "starlight-sidebar-topics": "^0.6.0", 26 | "starlight-sidebar-topics-dropdown": "^0.5.1", 27 | "svelte": "^5.28.2", 28 | "typescript": "^5.8.3", 29 | "unist-util-visit": "^5.0.0", 30 | "yaml": "^2.7.1" 31 | }, 32 | "devDependencies": { 33 | "@types/mdast": "^4.0.4", 34 | "@types/node": "^22.15.16", 35 | "dead-or-alive": "^1.0.4", 36 | "prettier": "3.5.3", 37 | "prettier-plugin-astro": "0.14.1", 38 | "prettier-plugin-organize-imports": "^4.1.0", 39 | "prettier-plugin-svelte": "^3.3.3" 40 | }, 41 | "engines": { 42 | "node": "22.x" 43 | }, 44 | "packageManager": "pnpm@10.8.0+sha512.0e82714d1b5b43c74610193cb20734897c1d00de89d0e18420aebc5977fa13d780a9cb05734624e81ebd81cc876cd464794850641c48b9544326b5622ca29971" 45 | } 46 | -------------------------------------------------------------------------------- /pnpm-workspace.yaml: -------------------------------------------------------------------------------- 1 | patchedDependencies: 2 | '@astrojs/starlight@0.34.3': patches/@astrojs__starlight@0.34.3.patch 3 | -------------------------------------------------------------------------------- /public/manifest.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "PaperMC Docs", 3 | "short_name": "Docs", 4 | "theme_color": "#004ee9", 5 | "background_color": "#424242", 6 | "display": "standalone", 7 | "scope": "./", 8 | "start_url": "./index.html", 9 | "related_applications": [ 10 | { 11 | "platform": "webapp", 12 | "url": "https://docs.papermc.io/manifest.json" 13 | } 14 | ], 15 | "icons": [ 16 | { 17 | "src": "https://assets.papermc.io/brand/papermc_logo.256.png", 18 | "sizes": "256x256", 19 | "type": "image/png" 20 | }, 21 | { 22 | "src": "https://assets.papermc.io/brand/papermc_logo.512.png", 23 | "sizes": "512x512", 24 | "type": "image/png" 25 | } 26 | ] 27 | } 28 | -------------------------------------------------------------------------------- /src/components/LinkCard.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import { Icon } from "@astrojs/starlight/components"; 3 | import type { ComponentProps } from "astro/types"; 4 | 5 | interface Props { 6 | icon?: ComponentProps["name"]; 7 | title: string; 8 | href: string; 9 | destructive?: boolean; 10 | } 11 | 12 | const { icon, title, href, destructive } = Astro.props; 13 | --- 14 | 15 | 16 |
17 |
18 | {icon && } 19 | 20 | {destructive && } 21 |
22 |
23 |
24 | 25 | 26 | 93 | -------------------------------------------------------------------------------- /src/components/PageCards.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import { CardGrid, LinkCard } from "@astrojs/starlight/components"; 3 | import { getCollection } from "astro:content"; 4 | import { flattenEntries } from "../utils/sidebar"; 5 | 6 | interface Props { 7 | path?: string; 8 | } 9 | 10 | let { path } = Astro.props; 11 | 12 | path = path ?? Astro.locals.starlightRoute.entry.filePath; 13 | const parent = path.substring(0, path.lastIndexOf("/") + 1); 14 | 15 | interface Page { 16 | title: string; 17 | description?: string; 18 | href: string; 19 | group: boolean; 20 | } 21 | 22 | const entries = flattenEntries(Astro.locals.starlightRoute.sidebar); 23 | const pages: Page[] = (await getCollection(Astro.locals.starlightRoute.entry.collection)) 24 | .filter((p) => p.filePath!.startsWith(parent) && p.filePath !== path) 25 | .filter((p) => { 26 | const rel = p.filePath!.substring(parent.length); 27 | 28 | return !rel.includes("/") || rel.match(/^[A-z0-9-_]+\/index\.mdx?$/); 29 | }) 30 | .map((p) => ({ 31 | title: p.data.title, 32 | description: p.data.description, 33 | href: `/${p.id}`, 34 | group: p.filePath!.includes("index"), 35 | })) 36 | .sort((a, b) => entries.findIndex((e) => e.label === a.title) - entries.findIndex((e) => e.label === b.title)); 37 | --- 38 | 39 | 40 | { 41 | pages.map((p) => ( 42 | 47 | )) 48 | } 49 | 50 | -------------------------------------------------------------------------------- /src/components/Version.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import { Icon } from "@astrojs/starlight/components"; 3 | 4 | interface Props { 5 | version: string; 6 | inline?: boolean; 7 | } 8 | 9 | const { version, inline } = Astro.props; 10 | --- 11 | 12 |
13 | 14 |
15 | Written for version: 16 | {version} 17 |
18 |
19 | 20 | 67 | -------------------------------------------------------------------------------- /src/components/Video.astro: -------------------------------------------------------------------------------- 1 | --- 2 | interface Props { 3 | src: string; 4 | } 5 | 6 | const { src } = Astro.props; 7 | --- 8 | 9 | 13 | -------------------------------------------------------------------------------- /src/components/overrides/Banner.astro: -------------------------------------------------------------------------------- 1 | --- 2 | const { banner } = Astro.locals.starlightRoute.entry.data; 3 | --- 4 | 5 | {banner &&
} 6 | 7 | 26 | -------------------------------------------------------------------------------- /src/components/overrides/Footer.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import Default from "@astrojs/starlight/components/Footer.astro"; 3 | import { Icon } from "@astrojs/starlight/components"; 4 | --- 5 | 6 | 7 |
8 |

9 | Copyright © {new Date().getFullYear()} PaperMC and contributors. Built with 10 | Starlight. 11 |

12 |

13 | This website is not an official Minecraft website and is not associated with Mojang Studios or Microsoft. All 14 | product and company names are trademarks or registered trademarks of their respective holders. Use of these names 15 | does not imply any affiliation or endorsement by them. 16 |

17 |
18 | 19 | 39 | -------------------------------------------------------------------------------- /src/components/overrides/LastUpdated.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import { REPO, getCommitInfo } from "../../utils/git"; 3 | 4 | const { lang, lastUpdated } = Astro.locals.starlightRoute; 5 | const filePath = Astro.locals.starlightRoute.entry.filePath; 6 | 7 | const info = await getCommitInfo(filePath); 8 | --- 9 | 10 | { 11 | lastUpdated && ( 12 |

13 | 14 | Last updated: 15 | 21 | {" "} 22 | {info && ( 23 | 24 | by {info.committer.name} 25 | in {info.hash.substring(0, 7)} 26 | 27 | )} 28 |

29 | ) 30 | } 31 | 32 | 42 | -------------------------------------------------------------------------------- /src/components/overrides/MobileTableOfContents.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import Default from "@astrojs/starlight/components/MobileTableOfContents.astro"; 3 | import Version from "../Version.astro"; 4 | 5 | const { version } = Astro.locals.starlightRoute.entry.data; 6 | --- 7 | 8 | 9 | {version && } 10 | -------------------------------------------------------------------------------- /src/components/overrides/PageFrame.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import MobileMenuToggle from "@astrojs/starlight/components/MobileMenuToggle.astro"; 3 | import TopicsDropdown from "starlight-sidebar-topics-dropdown/TopicsDropdown.astro"; 4 | 5 | const { hasSidebar } = Astro.locals.starlightRoute; 6 | --- 7 | 8 |
9 |
10 | { 11 | hasSidebar && ( 12 | 23 | ) 24 | } 25 |
26 |
27 | 28 | 36 | 37 | 127 | -------------------------------------------------------------------------------- /src/components/overrides/SiteTitle.astro: -------------------------------------------------------------------------------- 1 | --- 2 | const { siteTitle, siteTitleHref } = Astro.locals.starlightRoute; 3 | --- 4 | 5 | 6 | PaperMC Logo (Light) 11 | PaperMC Logo (Dark) 16 | {siteTitle} 17 | 18 | 19 | 37 | -------------------------------------------------------------------------------- /src/components/overrides/SocialIcons.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import config from "virtual:starlight/user-config"; 3 | import { Icon } from "@astrojs/starlight/components"; 4 | import { LATEST_RELEASES } from "../../utils/versions"; 5 | 6 | const { isPageWithTopic, topics } = Astro.locals.starlightSidebarTopics; 7 | const currentTopic = isPageWithTopic ? topics.find((t) => t.isCurrent) : null; 8 | 9 | const links = (config.social || []).map((link) => { 10 | const project = currentTopic?.label?.toLowerCase(); 11 | if (!project) { 12 | return link; 13 | } 14 | 15 | const version = LATEST_RELEASES[project]; 16 | if (!version) { 17 | return link; 18 | } 19 | 20 | switch (link.label) { 21 | case "Javadoc": 22 | return { ...link, href: `${link.href}/${project}/${version}` }; 23 | case "GitHub": 24 | return { ...link, href: `${link.href}/${project}` }; 25 | } 26 | return link; 27 | }); 28 | --- 29 | 30 | { 31 | links.length > 0 && ( 32 | <> 33 | {links.map(({ label, href, icon }) => ( 34 | 35 | {label} 36 | 37 | 38 | ))} 39 | 40 | ) 41 | } 42 | 43 | 53 | -------------------------------------------------------------------------------- /src/components/overrides/TableOfContents.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import Default from "@astrojs/starlight/components/TableOfContents.astro"; 3 | import Version from "../Version.astro"; 4 | 5 | const { version } = Astro.locals.starlightRoute.entry.data; 6 | --- 7 | 8 | {version && } 9 | 10 | -------------------------------------------------------------------------------- /src/config/paper/banned-ips-single.yml: -------------------------------------------------------------------------------- 1 | header: 2 | message: This is a single entry in the root array found in banned-ips.json. 3 | ip: 4 | description: | 5 | The IP address representing the banned user. 6 | 7 | For IPv4 the expected format is "x.x.x.x", 8 | 9 | For IPv6 the expected format follows [RFC5952 Section 4](https://datatracker.ietf.org/doc/html/rfc5952#section-4), 10 | 11 | For anything else, "\" may be present (but its use is discouraged). 12 | default: "an IPv4 or IPv6 address" 13 | created: 14 | description: | 15 | A timestamp of when the user was banned. 16 | The expected format is "yyyy-MM-dd HH:mm:ss Z". 17 | default: the ban creation time 18 | source: 19 | description: A string representing the source of the ban. 20 | default: '"(Unknown)"' 21 | expires: 22 | description: | 23 | A timestamp of when the ban expires, or "forever" if it does not expire. 24 | 25 | The expected format is "yyyy-MM-dd HH:mm:ss Z". 26 | default: '"forever"' 27 | reason: 28 | description: The reason for the ban. 29 | default: '"Banned by an operator."' 30 | -------------------------------------------------------------------------------- /src/config/paper/banned-players-single.yml: -------------------------------------------------------------------------------- 1 | header: 2 | message: This is a single entry in the root array found in banned-players.json. 3 | uuid: 4 | description: The UUID representing the banned user. 5 | default: the UUID of the banned user 6 | name: 7 | description: The name of the banned user. 8 | default: the name of the banned user 9 | created: 10 | description: | 11 | A timestamp of when the user was banned. 12 | The expected format is "yyyy-MM-dd HH:mm:ss Z". 13 | default: the ban creation time 14 | source: 15 | description: A string representing the source of the ban. 16 | default: '"(Unknown)"' 17 | expires: 18 | description: | 19 | A timestamp of when the ban expires, or "forever" if it does not expire. 20 | 21 | The expected format is "yyyy-MM-dd HH:mm:ss Z". 22 | default: '"forever"' 23 | reason: 24 | description: The reason for the ban. 25 | default: '"Banned by an operator."' 26 | -------------------------------------------------------------------------------- /src/config/paper/commands.yml: -------------------------------------------------------------------------------- 1 | command-block-overrides: 2 | default: "[]" 3 | description: > 4 | Which Vanilla commands should be prioritized over those provided by Bukkit 5 | or plugins. Useful for compatibility with adventure maps built for Vanilla 6 | command blocks. 7 | 8 | Use the literal ''*'' to always use the Vanilla version in command blocks. 9 | 10 | By default, no commands are overridden. 11 | ignore-vanilla-permissions: 12 | default: "false" 13 | description: Whether to use Vanilla permission levels when executing commands. 14 | aliases: 15 | : 16 | default: "[]" 17 | description: > 18 | A list of strings which are target commands. Alternatively, a string, 19 | which is a single target command. 20 | 21 | A target command is a command that is run, when the alias is run. 22 | 23 | Replacements: 24 | 25 | * `$sender` is replaced with the command sender''s name (Added by Paper). 26 | * `$` is replaced by the n''th argument, 1-indexed. 27 | * `$$` is replaced by the n''th argument, 1-indexed, failing if the n''th argument is not present. 28 | * `$-` is replaced by the n''th argument and everything that follows, 1-indexed. 29 | * `$$-` is replaced by the n''th argument and everything that follows, 1-indexed, failing if the n''th argument is not present. 30 | 31 | 32 | Each alias registered cannot (easily) be overridden by a plugin. 33 | icanhasbukkit: 34 | default: "[version $1-]" 35 | description: >- 36 | A built-in alias. Set aliases to an empty list ([]) to persistently 37 | remove. 38 | -------------------------------------------------------------------------------- /src/config/paper/eula.yml: -------------------------------------------------------------------------------- 1 | header: 2 | message: | 3 | #By changing the setting below to TRUE you are indicating your agreement to our EULA (https://aka.ms/MinecraftEULA). 4 | 5 | #\ 6 | inline: true 7 | eula: 8 | default: "false" 9 | description: >- 10 | Whether to accept the Minecraft EULA. 11 | This must be set to "true" to run the server. 12 | -------------------------------------------------------------------------------- /src/config/paper/help.yml: -------------------------------------------------------------------------------- 1 | general-topics: 2 | : 3 | header: 4 | message: A custom help "topic" to show when the user types "`/help `". 5 | shortText: 6 | description: | 7 | The first line of the help entry, used as a summary in index pages. 8 | 9 | This is formatted with legacy "&" style formatting. 10 | fullText: 11 | description: | 12 | The remaining lines of this help entry. 13 | 14 | This is formatted with legacy "&" style formatting. 15 | permission: 16 | description: | 17 | The permission required to view this help entry. 18 | 19 | If this is empty/not set, the entry does not require a permission. 20 | 21 | index-topics: 22 | : 23 | header: 24 | message: | 25 | A composite help topic index. 26 | 27 | If the topic name is the special value "Default", 28 | it will override the automatically generated index used for /help with no arguments. 29 | shortText: 30 | description: | 31 | The short text used in other index topics. 32 | 33 | This is not displayed when showing this topic itself. 34 | 35 | This is formatted with legacy "&" style formatting. 36 | preamble: 37 | description: | 38 | Information to show before the index. 39 | 40 | This is formatted with legacy "&" style formatting. 41 | permission: 42 | description: | 43 | A custom permission required to view this help entry. 44 | 45 | If this is empty/not set, the entry does not require a permission. 46 | commands: 47 | description: | 48 | What to show in the index. 49 | 50 | This is a list of commands, or other help topics. 51 | 52 | They will be displayed in the order they are listed here 53 | in "topic name: short text" format. 54 | 55 | Each entry is a maximum of 1 minimum-width chat line (55 chars). 56 | default: "[]" 57 | 58 | amended-topics: 59 | : 60 | shortText: 61 | description: | 62 | A replacement for the short text of the topic. 63 | 64 | If this is empty/not set, the original short text is used. 65 | 66 | If this contains the literal string ``, it will be replaced with the original short text. 67 | 68 | This is formatted with legacy "&" style formatting. 69 | fullText: 70 | description: | 71 | A replacement for the full text of the topic. 72 | 73 | If this is empty/not set, the original full text is used. 74 | 75 | If this contains the literal string ``, it will be replaced with the original full text. 76 | 77 | This is formatted with legacy "&" style formatting. 78 | permission: 79 | description: | 80 | Overrides the permission required to view this help entry. 81 | 82 | If this is empty/not set, the original permission is NOT used, instead no permission is required. 83 | 84 | ignore-plugins: 85 | description: | 86 | A list of plugins to ignore when generating help topics for registered commands. 87 | 88 | If "All" is included, all plugins are ignored. 89 | 90 | If the special plugin name "Bukkit" is included, all commands registered by Bukkit are ignored. 91 | default: "[]" 92 | 93 | command-topics-in-master-index: 94 | description: | 95 | Whether to allow command topics (topics starting with a `/`) to be shown in the main index. 96 | 97 | This is the index shown when the user types "`/help`" or "`/help `". 98 | Command alias topics are always hidden. 99 | default: "true" 100 | -------------------------------------------------------------------------------- /src/config/paper/ops-single.yml: -------------------------------------------------------------------------------- 1 | header: 2 | message: This is a single entry in the root array found in ops.json. 3 | uuid: 4 | description: The UUID representing the operator. 5 | default: the UUID of the operator 6 | name: 7 | description: The name of the operator. 8 | default: the name of the operator 9 | level: 10 | description: | 11 | The level of the operator permissions. 12 | 13 | The expected format is an integer between 0 and 4. 14 | default: "0" 15 | 16 | bypassesPlayerLimit: 17 | description: Whether this operator bypasses the player limit. 18 | default: "false" 19 | -------------------------------------------------------------------------------- /src/config/paper/permissions.yml: -------------------------------------------------------------------------------- 1 | : 2 | default: 3 | description: | 4 | Who this permission is granted to by default. 5 | 6 | "true": all players. 7 | 8 | "false": no players. 9 | 10 | "op": only operators (also aliased as "isop", "operator", "isoperator", "admin", and "isadmin"). 11 | 12 | "!op": all players except operators (also aliased as "notop", "!operator", "notoperator", "!admin", "notadmin"). 13 | default: "op" 14 | children: 15 | header: 16 | message: A list (not shown) or a map (shown below) of child permissions. 17 | : 18 | description: | 19 | A child permission of this permission. 20 | 21 | The value is either a boolean, where false inverts the whether the permission would be granted to this. 22 | 23 | or a top level permission entry, 24 | except the default is this parent permissions default value, 25 | and any child permissions of the newly created permission are bubbled up to the top level. 26 | default: "true" 27 | description_: 28 | description: The description of the permission. 29 | -------------------------------------------------------------------------------- /src/config/paper/whitelist-single.yml: -------------------------------------------------------------------------------- 1 | header: 2 | message: This is a single entry in the root array found in whitelist.json. 3 | uuid: 4 | description: The UUID of the player on the whitelist. 5 | default: the UUID of the player on the whitelist 6 | name: 7 | description: The name of the player on the whitelist. 8 | default: the name of the player on the whitelist 9 | -------------------------------------------------------------------------------- /src/config/waterfall/waterfall-config.yml: -------------------------------------------------------------------------------- 1 | use_netty_dns_resolver: 2 | default: "true" 3 | description: >- 4 | Sets whether Netty''s async DNS resolver is used for account authentication. 5 | disable_modern_tab_limiter: 6 | default: "true" 7 | description: >- 8 | Disables the tab completion limit for 1.13+ clients. 9 | log_initial_handler_connections: 10 | default: "true" 11 | description: >- 12 | Sets whether to log InitialHandler connections. 13 | throttling: 14 | default: "1000" 15 | description: >- 16 | How often tab-complete packets can be sent in milliseconds. 17 | game_version: 18 | default: "" 19 | description: >- 20 | The supported versions displayed to the client. Default is a comma 21 | separated list of supported versions. For example 1.8.x, 1.9.x, 1.10.x 22 | disable_tab_list_rewrite: 23 | default: "true" 24 | description: >- 25 | This setting disables tablist rewriting, which may resolve issues 26 | setting player profiles when Waterfall is in offline mode. 27 | disable_entity_metadata_rewrite: 28 | default: "false" 29 | description: >- 30 | This setting disables entity metadata rewriting in favor of sending 31 | a join packet to the client. It offers a more robust solution for modded environments 32 | but can cause plugins to break. 33 | plugin_channel_name_limit: 34 | default: "128" 35 | description: >- 36 | The maximum channel identifier length. May be useful for certain broken mods. 37 | registered_plugin_channels_limit: 38 | default: "128" 39 | description: >- 40 | The maximum number of registered plugin channels for a connection. 41 | Used by mods and some plugins. May be useful to fix certain broken modpacks. 42 | -------------------------------------------------------------------------------- /src/content.config.ts: -------------------------------------------------------------------------------- 1 | import { docsLoader } from "@astrojs/starlight/loaders"; 2 | import { docsSchema } from "@astrojs/starlight/schema"; 3 | import { defineCollection, z } from "astro:content"; 4 | 5 | export const collections = { 6 | docs: defineCollection({ 7 | loader: docsLoader(), 8 | schema: docsSchema({ 9 | extend: z.object({ 10 | banner: z 11 | .object({ 12 | destructive: z.boolean().optional(), 13 | }) 14 | .optional(), 15 | version: z.string().optional(), 16 | }), 17 | }), 18 | }), 19 | }; 20 | -------------------------------------------------------------------------------- /src/content/docs/folia/admin/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Administration 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Welcome to the Folia administration guide! This guide includes information and tutorials 9 | regarding the administration of a Folia server. 10 | 11 | #### Reference 12 | 13 | 14 | -------------------------------------------------------------------------------- /src/content/docs/folia/admin/reference/faq.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Frequently asked questions 3 | description: Questions frequently asked by our community, answered by us! 4 | slug: folia/faq 5 | --- 6 | 7 | ## What server types can benefit from Folia? 8 | Server types that naturally spread players out, 9 | like skyblock or SMP, will benefit the most from Folia. The server 10 | should have a sizeable player count, too. 11 | 12 | ## What hardware will Folia run best on? 13 | Ideally, at least 16 _cores_ (not threads). 14 | 15 | ## How to best configure Folia? 16 | First, it is recommended that the world is pre-generated so that the number 17 | of chunk system worker threads required is reduced greatly. 18 | 19 | The following is a _very rough_ estimation based off of the testing 20 | done before Folia was released on the test server we ran that 21 | had ~330 players peak. So, it is not exact and will require further tuning - 22 | just take it as a starting point. 23 | 24 | The total number of cores on the machine available should be 25 | taken into account. Then, allocate threads for: 26 | - netty IO: ~4 per 200-300 players 27 | - chunk system io threads: ~3 per 200-300 players 28 | - chunk system workers if pre-generated, ~2 per 200-300 players 29 | - There is no best guess for chunk system workers if not pre-generated, as 30 | on the test server we ran we gave 16 threads but chunk generation was still 31 | slow at ~300 players. 32 | - GC Settings: ???? But, GC settings _do_ allocate concurrent threads, and you need 33 | to know exactly how many. This is typically through the `-XX:ConcGCThreads=n` flag. Do not 34 | confuse this flag with `-XX:ParallelGCThreads=n`, as parallel GC threads only run when 35 | the application is paused by GC and as such should not be taken into account. 36 | 37 | After all of that allocation, the remaining cores on the system until 80% 38 | allocation (total threads allocated < 80% of cpus available) can be 39 | allocated to tickthreads (under global config, `threaded-regions.threads`). 40 | 41 | The reason you should not allocate more than 80% of the cores is due to the 42 | fact that plugins or even the server may make use of additional threads 43 | that you cannot configure or even predict. 44 | 45 | Additionally, the above is all a rough guess based on player count, but 46 | it is very likely that the thread allocation will not be ideal, and you 47 | will need to tune it based on usage of the threads that you end up seeing. 48 | 49 | ## What commands does Folia disable? 50 | Folia currently disables a handful of commands. These are them: 51 | - Bossbar commands 52 | - Clone commands 53 | - Data commands 54 | - Datapack 55 | - Debug 56 | - Function 57 | - Item commands 58 | - Loot 59 | - Reload 60 | - Ride 61 | - Schedule 62 | - Scoreboard 63 | - Tag 64 | - Team 65 | - TeamMsg 66 | - Trigger 67 | - WorldBorder 68 | - Perf 69 | - SaveAll 70 | - Restart 71 | -------------------------------------------------------------------------------- /src/content/docs/folia/admin/reference/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Reference 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | A reference of how Folia works. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/folia/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Folia Documentation 3 | tableOfContents: false 4 | --- 5 | 6 | import { CardGrid, LinkCard } from "@astrojs/starlight/components"; 7 | 8 | Folia is a fork of Paper which adds regionized multithreading to the dedicated server. 9 | 10 | 11 | 16 | 17 | -------------------------------------------------------------------------------- /src/content/docs/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Welcome 3 | description: Documentation for all projects under the PaperMC umbrella, including Paper, Velocity and Folia. 4 | template: splash 5 | editUrl: false 6 | lastUpdated: false 7 | hero: 8 | title: PaperMC Docs 9 | tagline: Documentation for all projects under the PaperMC umbrella, including Paper, Velocity and Folia. 10 | image: 11 | html: 'PaperMC Logo' 12 | --- 13 | 14 | import { CardGrid } from "@astrojs/starlight/components"; 15 | import { ContributorList } from "starlight-contributor-list"; 16 | import LinkCard from "/src/components/LinkCard.astro"; 17 | 18 | 19 | 20 | High performance Minecraft server that aims to fix gameplay and mechanics inconsistencies. 21 | 22 | 23 | The modern, next-generation Minecraft server proxy. 24 | 25 | 26 | A fork of Paper which adds regionized multithreading to the dedicated server. 27 | 28 | 29 | A discontinued BungeeCord proxy fork that aimed to improve performance and stability. 30 | 31 | 32 | A Java library for server-controllable user interface elements in Minecraft: Java Edition. 33 | 34 | 35 | Various other documentation and tools. 36 | 37 | 38 | 39 |
40 | 41 | ## [Contribute](https://github.com/PaperMC/docs) 42 | 43 | We’d like to extend a warm thank you to all the contributors who have helped bring this documentation site to life. 44 | Whether you've written code, submitted feedback, fixed a typo, or shared your expertise - every contribution is deeply appreciated. 45 | This is very much a team effort, and we’re grateful to have you with us on the journey! 46 | 47 | 48 | -------------------------------------------------------------------------------- /src/content/docs/misc/assets/github-secrets-actions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/misc/assets/github-secrets-actions.png -------------------------------------------------------------------------------- /src/content/docs/misc/assets/hangar-create-snapshot-channel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/misc/assets/hangar-create-snapshot-channel.png -------------------------------------------------------------------------------- /src/content/docs/misc/assets/pterodactyl-manual.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/misc/assets/pterodactyl-manual.png -------------------------------------------------------------------------------- /src/content/docs/misc/assets/pterodactyl-prompt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/misc/assets/pterodactyl-prompt.png -------------------------------------------------------------------------------- /src/content/docs/misc/contact.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contact us 3 | description: There are many ways to contact us, see here for more information. 4 | slug: misc/contact 5 | --- 6 | 7 | ## Discord 8 | 9 | The PaperMC project handles most communication via Discord. Use the following invite: https://discord.gg/papermc 10 | 11 | ## Forums 12 | 13 | Reach out for support, or contact us on our forums. 14 | 15 | - [Forums](https://forums.papermc.io) 16 | 17 | ## Twitter/X 18 | 19 | We often tweet out version release notes, update notices, and other information via our Twitter 20 | page. 21 | 22 | - [@PaperPowered](https://x.com/PaperPowered) 23 | 24 | You should not DM or @ this account for support. It is not checked as regularly as the above 25 | locations. 26 | -------------------------------------------------------------------------------- /src/content/docs/misc/downloads-api.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Downloads API 3 | description: Paper provides a downloads API that you can use to access builds. 4 | slug: misc/downloads-api 5 | --- 6 | 7 | PaperMC provides a downloads API to facilitate automated downloads access. Full documentation can be 8 | found on the [Downloads API Docs](https://api.papermc.io/docs). 9 | 10 | :::danger 11 | 12 | We emphatically **do not recommend** using unstable builds or auto-updaters within production environments. 13 | 14 | ::: 15 | 16 | :::note 17 | 18 | We require `jq` to be installed for the examples below. You can install it with `sudo apt-get install jq` on Debian/Ubuntu. 19 | 20 | ::: 21 | 22 | ## Getting the latest version 23 | 24 | ```shell 25 | #!/usr/bin/env sh 26 | 27 | PROJECT="paper" 28 | 29 | LATEST_VERSION=$(curl -s https://api.papermc.io/v2/projects/${PROJECT} | \ 30 | jq -r '.versions[-1]') 31 | 32 | echo "Latest version is $LATEST_VERSION" 33 | ``` 34 | 35 | This will get the latest available Minecraft version for the given project. 36 | 37 | ## Getting the latest stable build number 38 | 39 | ```shell replace 40 | #!/usr/bin/env sh 41 | 42 | PROJECT="paper" 43 | MINECRAFT_VERSION="\{LATEST_PAPER_RELEASE}" 44 | 45 | LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds | \ 46 | jq '.builds | map(select(.channel == "default") | .build) | .[-1]') 47 | 48 | if [ "$LATEST_BUILD" != "null" ]; then 49 | echo "Latest stable build is $LATEST_BUILD" 50 | else 51 | echo "No stable build for version $MINECRAFT_VERSION found :(" 52 | fi 53 | ``` 54 | 55 | This will get the latest stable build for the given project and Minecraft version, if it's available. 56 | 57 | ## Downloading the latest stable build 58 | 59 | ```shell replace 60 | #!/usr/bin/env sh 61 | 62 | PROJECT="paper" 63 | MINECRAFT_VERSION="\{LATEST_PAPER_RELEASE}" 64 | 65 | LATEST_BUILD=$(curl -s https://api.papermc.io/v2/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds | \ 66 | jq -r '.builds | map(select(.channel == "default") | .build) | .[-1]') 67 | 68 | if [ "$LATEST_BUILD" != "null" ]; then 69 | JAR_NAME=${PROJECT}-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar 70 | PAPERMC_URL="https://api.papermc.io/v2/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds/${LATEST_BUILD}/downloads/${JAR_NAME}" 71 | 72 | # Download the latest Paper version 73 | curl -o server.jar $PAPERMC_URL 74 | echo "Download completed" 75 | else 76 | echo "No stable build for version $MINECRAFT_VERSION found :(" 77 | fi 78 | ``` 79 | 80 | This is the most common use case for the API. It will download the latest stable build for the given project and 81 | Minecraft version. You should always serve & use the stable builds. Experimental builds are prone to error and 82 | do not receive support. 83 | -------------------------------------------------------------------------------- /src/content/docs/misc/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Miscellaneous 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Documentation that does not cleanly fit in any other category. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/misc/tools/assets/adventure-webui.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/misc/tools/assets/adventure-webui.png -------------------------------------------------------------------------------- /src/content/docs/misc/tools/diff-viewer.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Diff viewer 3 | description: Multi-file rich diff viewer for GitHub and diff/patch files. 4 | slug: misc/tools/diff-viewer 5 | --- 6 | 7 | Multi-file rich diff viewer with support for GitHub commits, PRs, and comparisons, as well as 8 | diff and patch files. 9 | The GitHub diff viewer is a great tool for most use cases, but it has a variety of limitations, 10 | especially when dealing with large diffs where the viewer will perform poorly or even crash. 11 | The diffs.dev Diff Viewer aims to solve this problem while also providing a variety of additional 12 | features useful for PaperMC and generally, such as special handling for second-order diffs. We have 13 | also built a browser extension for Firefox and Chrome to streamline opening GitHub diffs in the 14 | viewer. 15 | 16 | - https://diffs.dev - The diff viewer itself 17 | - [Chrome Extension](https://chromewebstore.google.com/detail/patch-roulette/feaaoepdocmiibjilhoahgldkaajfnhb) 18 | - [Firefox Add-on](https://addons.mozilla.org/en-US/firefox/addon/patch-roulette/) 19 | - https://github.com/PaperMC/diff-viewer - GitHub repository 20 | -------------------------------------------------------------------------------- /src/content/docs/misc/tools/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Tools 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Collection of useful tools for server admins or plugin developers. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/misc/tools/item-command-converter.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Item command converter 3 | description: A tool to update commands from the old NBT-based item format to item components. 4 | slug: misc/tools/item-command-converter 5 | tableOfContents: false 6 | --- 7 | 8 | import ItemCommandConverter from "/src/components/tools/ItemCommandConverter.svelte"; 9 | 10 | In 1.20.5, Mojang has moved from unstructured NBT to the so-called item components. While Minecraft 11 | will automatically update all existing items for you, only Paper will update commands and text 12 | components containing items where possible. This tool helps you convert old item commands to the 13 | new format externally. 14 | 15 | 16 | Note that you need to select the *Entity Argument* mode if you want to convert entity data outside of 17 | the summon command, as we require the entity type to convert data correctly. 18 | 19 |
20 | 21 | 22 | -------------------------------------------------------------------------------- /src/content/docs/misc/tools/minimessage-web-editor.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: MiniMessage web editor 3 | description: A web-based editor for creating and previewing MiniMessage-formatted text. 4 | slug: misc/tools/minimessage-web-editor 5 | --- 6 | 7 | The MiniMessage Web Editor is a web-based editor for creating and previewing MiniMessage-formatted text. 8 | 9 | 10 | It is hosted here: [MiniMessage Web Editor](https://webui.advntr.dev/). 11 | 12 | ![Image of adventure webui](./assets/adventure-webui.png) 13 | -------------------------------------------------------------------------------- /src/content/docs/misc/tools/start-script-gen.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Start script generator 3 | description: A start script generator for PaperMC projects. 4 | slug: misc/tools/start-script-gen 5 | tableOfContents: false 6 | --- 7 | 8 | import StartScriptGenerator from "/src/components/tools/StartScriptGenerator.svelte"; 9 | 10 |
11 | What flags do I choose? 12 | If you're running on a modern JVM, i.e. 17, 21 or higher, try with no flags first. 13 | Modern JVMs are very good at handling various applications with default GC settings. 14 | 15 | If you have GC problems or are running an older version of Minecraft/an older version of Java, 16 | try [Aikar's flags](/paper/aikars-flags), which are optimized specifically for Minecraft. 17 | 18 | If you're generating a script for starting [Velocity](https://papermc.io/software/velocity), choose "Velocity". 19 |
20 | 21 |
22 | 23 | 24 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/getting-started/assets/hangar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/admin/getting-started/assets/hangar.png -------------------------------------------------------------------------------- /src/content/docs/paper/admin/getting-started/getting-started.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting started 3 | description: How to get started with downloading and setting up a Paper server. 4 | slug: paper/getting-started 5 | --- 6 | 7 | ## Requirements 8 | 9 | :::tip 10 | 11 | Paper requires at least **Java 21** to run, which [is easy to download and install](/misc/java-install). 12 | 13 | ::: 14 | 15 | | Paper Version | Recommended Java Version | 16 | |----------------|--------------------------| 17 | | 1.8 to 1.11 | Java 8 | 18 | | 1.12 to 1.16.4 | Java 11 | 19 | | 1.16.5 | Java 16 | 20 | | 1.17.1-1.18.1+ | Java 21 | 21 | 22 | ## Downloading Paper 23 | 24 | Paper provides runnable server JARs directly from our 25 | [website's downloads page](https://papermc.io/downloads). 26 | 27 | Click on the build number to download a file. 28 | 29 | ## Running the server 30 | 31 | To run the server you will need to either create a startup script 32 | or run a command in your terminal. 33 | 34 | You can generate a startup script using our [Startup Script Generator](/misc/tools/start-script-gen). 35 | You can also obtain the optimized terminal command to run the server there. 36 | 37 | If you're just looking for a short command: 38 | ```bash 39 | java -Xms4G -Xmx4G -jar paper.jar --nogui 40 | ``` 41 | Ensure you navigated your terminal to the directory of your server 42 | and that you have replaced `paper.jar` with the name of the JAR you have downloaded. 43 | 44 | The amount of RAM can be set by changing the numbers in the `Xmx` and `Xms` arguments. 45 | `--nogui` disables Vanilla's GUI, so you don't get double interfaces when using the command line. 46 | 47 | To configure your server, see the [Global Configuration](/paper/reference/global-configuration) and 48 | [Per World Configuration](/paper/reference/world-configuration) pages. 49 | 50 | ## Updating the server 51 | 52 | Updating Paper is simple! See our [Update Tutorial](/paper/updating) for more information. 53 | 54 | ## Migrating to Paper 55 | 56 | ### From Vanilla 57 | 58 | Migrating from Vanilla is easy, but there are some differences, namely in world saves. Paper (and 59 | CraftBukkit and Spigot) separate out each dimension of a world (nether, the end, etc.) into separate 60 | world folders. 61 | 62 | Paper will handle this conversion for you automatically. No additional consideration is required. 63 | 64 | ### From CraftBukkit or Spigot 65 | 66 | Paper is a drop in replacement for both CraftBukkit and Spigot, you don't need to make any changes. 67 | 68 | ## Next steps 69 | 70 | Take a look at our [Next Steps](/paper/next-steps) guide to get your server up and running with the best performance and 71 | features. 72 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/getting-started/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting started 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Guides for getting started with running a Paper server. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/getting-started/next-steps.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Next steps 3 | description: How to proceed after starting your server. 4 | slug: paper/next-steps 5 | --- 6 | 7 | Now that you have your server up and running, there are a few things you should do to ensure that your server is running smoothly. 8 | 9 | ## Configuration 10 | 11 | One of the first things you should do is ensure your server is configured to your specifications. 12 | Paper is highly configurable, and you can change many settings to suit your needs. We outline where 13 | you can find these settings in the [Configuration](/paper/reference/configuration) guide. 14 | 15 | ## Plugins 16 | 17 | One of the main reasons to use Paper is to take advantage of the many plugins which make use of our 18 | expansive API. We have our own plugin repository, [Hangar](https://hangar.papermc.io/), where you can 19 | find many plugins to use on your server. We also have a guide on how to install plugins 20 | [here](/paper/adding-plugins). 21 | 22 | ![Hangar](./assets/hangar.png) 23 | 24 | ## Security 25 | 26 | ### Whitelisting 27 | 28 | If you want to restrict who can join your server, you can use the whitelist feature. This allows you to 29 | specify who can join your server, and stops anyone else from joining. You can use the whitelist from 30 | the server console, or by editing the `whitelist.json` file in your server directory. 31 | 32 | ### Permissions 33 | 34 | Permissions are a way to control what players can and cannot do on your server. You can use permissions 35 | to restrict who can use certain commands, or who can access certain areas of your server. It is 36 | common for plugins to use permissions to control who can use their features. You can use permission 37 | plugins such as [LuckPerms](https://luckperms.net/) to manage the permissions which players will be granted. 38 | 39 | ## Backups 40 | 41 | It's important to keep backups of your server. If something goes wrong, you can restore your server to a 42 | previous state. We cover how to do this in the [Updating](/paper/updating) guide. 43 | 44 | ## Optimization 45 | 46 | Out of the box, Paper is optimized for performance. However, there are many things you can do to further 47 | optimize your server. One of the most common things to do is to make sure that you are running the 48 | correct startup flags for your server. We have a tool that allows you to automatically generate a 49 | startup script with the correct flags for your server. You can find this tool 50 | [here](/misc/tools/start-script-gen). Beyond this, a guide such as [this one](https://paper-chan.moe/paper-optimization/) 51 | will help you to further optimize your server. 52 | 53 | ## Making your server public 54 | 55 | If you want to make your server public, you will need to port forward your server. This allows people 56 | from outside your network to connect to your server. There is a guide made by 57 | [NordVPN](https://nordvpn.com/blog/open-ports-on-router/) which explains what port forwarding is and how 58 | to do it for your Paper server. 59 | 60 | ## Troubleshooting 61 | 62 | If you encounter any issues with your server, you can follow our [Troubleshooting](/paper/basic-troubleshooting) 63 | guide to help you diagnose and fix the issue. If you are unable to fix the issue, you can come and 64 | ask for help in our [Discord](https://discord.gg/papermc) server! 65 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/how-to/assets/anti-xray-nether.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/admin/how-to/assets/anti-xray-nether.png -------------------------------------------------------------------------------- /src/content/docs/paper/admin/how-to/assets/anti-xray-overworld.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/admin/how-to/assets/anti-xray-overworld.png -------------------------------------------------------------------------------- /src/content/docs/paper/admin/how-to/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: How-to guides 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | How-to guides for setting up specific features of Paper and managing the server. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/how-to/profiling.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Profiling 3 | description: How to profile your Paper server. 4 | slug: paper/profiling 5 | --- 6 | 7 | Profiling is a way to diagnose performance problems with your server. 8 | A profiler measures certain characteristics of a running server, e.g. how often a method is called 9 | and how much time it takes up in a single tick, how long and often the garbage collector runs and much more. 10 | 11 | :::caution 12 | 13 | _For profiling to be effective, the issue you are diagnosing must be actively occurring._ 14 | 15 | ::: 16 | 17 | If you need help with analyzing a performance issue, please bring a spark report to the 18 | [PaperMC Discord server](https://discord.gg/PaperMC) (#paper-help) for assistance. 19 | 20 | ## spark 21 | 22 | Starting with 1.21, Paper bundles the [spark](https://spark.lucko.me/) profiler, which is the preferred way 23 | to profile Paper. 24 | 25 | To start profiling your server, run this command: 26 | ``` 27 | /spark profiler start --timeout 600 28 | ``` 29 | 30 | After 10 minutes, this will return a URL to a profiler report, which you can analyze yourself or provide 31 | to a developer of a plugin or the Paper support chats. 32 | 33 | This is only a fraction of what spark can do, so if you want to learn about the different features of spark 34 | or learn to analyze reports yourself, check out spark's documentation [here](https://spark.lucko.me/docs/). 35 | 36 | :::tip 37 | 38 | If you want to use a version of spark newer than the bundled one, simply place a standalone spark plugin JAR 39 | into the `plugins` directory and set the [`paper.preferSparkPlugin`](/paper/reference/system-properties#paperprefersparkplugin) 40 | system property to `true`. 41 | 42 | If you want to use PlaceholderAPI [placeholders](https://spark.lucko.me/docs/misc/Placeholders) 43 | from the bundled spark version, you need to install the [spark expansion](https://api.extendedclip.com/expansions/spark/) 44 | from PAPI's eCloud (`/papi ecloud download spark` and `/papi reload`). 45 | 46 | ::: 47 | 48 | ## Timings 49 | 50 | Paper also bundles the [Timings v2](https://timings.aikar.co/) profiler, however Timings has been unmaintained 51 | for multiple years and its reports are difficult to read for beginners. It has been deprecated in favor of 52 | spark and turned off by default in 1.21, see [this discussion](https://github.com/PaperMC/Paper/discussions/10565) 53 | for more information. 54 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/how-to/update.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Updating 3 | description: Paper has new features and fixes coming every day, this guide explains the updating process. 4 | slug: paper/updating 5 | --- 6 | 7 | Updating Paper is an important part of running every server. With new features and fixes coming 8 | every day, we recommend updating at least once per week to keep your server patched for the latest 9 | bugs. Installing updates is very simple, but it's important to know how to do it correctly. 10 | 11 | :::caution[Don't replace any JAR in a running server] 12 | 13 | Unless you know exactly what and why you're doing what you're doing, it's never a good idea to 14 | replace any JAR in a running server, be that plugins, or Paper itself. 15 | 16 | ::: 17 | 18 | ## Step 1. Backup 19 | 20 | :::tip 21 | 22 | If you are using a shared host, your host may provide a built-in way to back up. Consult their 23 | documentation before continuing. 24 | 25 | ::: 26 | 27 | This is the most important step, and yet the most frequently skipped. While it is unlikely that 28 | updating Paper itself will cause any issues requiring you to restore from a backup, plugin 29 | malfunctions or other accidents might! Updating is a great time to work in a backup. Having 30 | functioning backups is essential to every server, big or small. The main things to back up are: 31 | 32 | - The world folders 33 | - Server Configuration Files 34 | - Plugin Configuration Files & Plugin JARs 35 | 36 | You should aim to have backups from multiple times, and keep them in a safe place. A common approach 37 | is to keep rolling backups, so you always have a certain number of backups from a set amount of time. 38 | 39 | ## Step 2. Update plugins 40 | 41 | Just like it's important to update Paper, it's equally important to keep plugins up to date. You 42 | never know what plugin authors may be working on, be it bugfixes or new features. 43 | 44 | A little known feature of Paper servers is the `update` folder. Here's how you use it. 45 | 46 | 1. Create a folder called `update` within the `plugins` folder. 47 | 2. One by one, download plugins you would like to update and put them in the `update` folder. 48 | 3. Restart your server, do not remove or modify any plugins outside the `update` folder. 49 | 50 | By doing this, you are able to update all of your plugins at the same time without having the server 51 | off, or replacing plugin JARs while the server is running. You do not need to restart your server 52 | before updating Paper itself. This feature allows you to update both Paper and plugins all at the 53 | same time, without needing any additional downtime. 54 | 55 | ## Step 3. Update Paper 56 | 57 | :::tip 58 | 59 | If you are using a shared host, your host may provide a built-in way to update! Consult their 60 | documentation before continuing. 61 | 62 | ::: 63 | 64 | Updating Paper itself is very simple. 65 | 66 | 1. Download a new JAR from [our downloads page](https://papermc.io/downloads). 67 | 2. Stop your server. It is not recommended and may cause issues to replace your Paper JAR while the server is running. 68 | 3. Rename the downloaded file to match the name specified in the [start command](/paper/getting-started#running-the-server). 69 | 4. Replace your old Paper JAR file with the new renamed one. 70 | 5. Start your server. Watch the startup log to ensure everything goes to plan. If there are any 71 | plugin conflicts or issues, you will see them here. 72 | 73 | To minimize downtime caused by updates, some server owners will, rather than replacing their server 74 | JAR, upload a new one and set their start script to use the new one on the next restart. Both of 75 | these are valid update strategies. 76 | 77 | :::caution[Automatic Updates] 78 | 79 | While it may be convenient to install updates automatically (and Paper's [downloads API](/misc/downloads-api) allows you 80 | to with ease), doing so is not recommended by Paper due to the possibility of plugin conflicts or 81 | other issues that you may not know about. Always be present during updates, and keep a careful watch 82 | on your server's log after the fact. 83 | 84 | If you do choose to automatically install updates, ensure you have a functioning backup strategy in 85 | place! 86 | 87 | ::: 88 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/how-to/vanilla.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Vanilla-like experience 3 | description: This page lists all changes that result in a different experience than Vanilla. 4 | slug: paper/vanilla 5 | --- 6 | 7 | import ConfigNode from "/src/components/ConfigNode.astro"; 8 | import { filterVanilla } from "/src/utils/config"; 9 | import { parse } from "yaml"; 10 | 11 | import ServerPropertiesYML from "/src/config/paper/server-properties.yml?raw"; 12 | import PaperWorldDefaultsYML from "/src/config/paper/paper-world-defaults.yml?raw"; 13 | import PaperGlobalYML from "/src/config/paper/paper-global.yml?raw"; 14 | import SpigotYML from "/src/config/paper/spigot.yml?raw"; 15 | 16 | Due to the way the Bukkit API is implemented in Paper, the gameplay experience between Vanilla and Paper can have inconsistencies. 17 | This can be furthered by efforts to fix bugs present in Vanilla Minecraft. 18 | Whilst many people may not notice the inconsistencies, there are situations where they become problematic. 19 | One example is that technical players may struggle getting their machines to work like they should. 20 | This page aims to provide a starting point for players who want to get as close to Vanilla as possible. 21 | 22 | :::note 23 | 24 | This page is inspired by [Earthcomputer's collection](https://gist.github.com/Earthcomputer/2296da33b8cc91dba81b48103c0e1fe3) of Vanilla breaking changes. 25 | 26 | ::: 27 | 28 | :::caution 29 | 30 | This guide will only help you to get as close to Vanilla as possible. 31 | Unfortunately, it currently is not possible to get a 100% Vanilla experience in Paper. 32 | 33 | ::: 34 | ## server.properties 35 | 36 | 37 | ## paper-world-defaults.yml 38 | 39 | 40 | ## paper-global.yml 41 | 42 | 43 | ## spigot.yml 44 | 45 | 46 | ## Further considerations 47 | 48 | * `settings.timeout-time` in `spigot.yml` mirrors the watchdog setting in the `server.properties` file. Keep in mind that the `spigot.yml` setting is in seconds while the default setting is in milliseconds. 49 | * `watchdog` in `paper-global.yml` controls the watchdog early warning. While this is only a warning, you might want to disable it as it can get annoying. 50 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Administration 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Welcome to the Paper administration guide! This guide includes information and tutorials 9 | regarding the administration of a Paper server. 10 | 11 | #### Getting started 12 | 13 | 14 | 15 | #### How-to guides 16 | 17 | 18 | 19 | #### Reference 20 | 21 | 22 | 23 | #### Miscellaneous 24 | 25 | 26 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/misc/faq.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Frequently asked questions 3 | description: Questions frequently asked by our community, answered by us! 4 | slug: paper/faq 5 | --- 6 | 7 | ## Unsupported Java detected, what do I do?! 8 | 9 | Unsupported, early-access, or internal versions of Java are often missing features, have known issues or be straight up broken. 10 | As such, we cannot provide support for servers running such versions. 11 | You should install a supported version of Java as explained [here](/misc/java-install). 12 | 13 | If you still wish to continue, knowing that you are on your own and will receive NO support, you can disable the check with a system property, as explained [here](/paper/reference/system-properties#paperignorejavaversion). 14 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/misc/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Miscellaneous 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Miscellaneous documentation pertaining to Paper. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/misc/paper-bug-fixes.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Bug fixes 3 | description: An explanation of which Vanilla bugs we fix in Paper. 4 | slug: paper/misc/paper-bug-fixes 5 | --- 6 | 7 | Paper fixes many gameplay and technical issues within Minecraft. The most prevalent fixes are to TNT duplication and bedrock breaking. 8 | 9 | ## Vanilla bug fixes 10 | 11 | Paper fixes many Vanilla bugs that were not intended by Mojang. These bugs are patched to fix behavior or prevent abuse and 12 | instability on the server. Some of our fixes are configurable, as we understand that some servers may want to keep the 13 | Vanilla behavior. You will find these configuration options in the [global configuration](/paper/reference/global-configuration) 14 | and the [world configuration](/paper/reference/world-configuration). 15 | 16 | ### What is intended behavior vs a bug? 17 | 18 | When an issue is reported to us, we check Mojang's issue tracker. If the problem has been reported there, then we 19 | check to see if it: 20 | 21 | 1) Has been confirmed as a bug 22 | 2) Has an assigned priority to it 23 | 24 | If it meets these two criteria then we will accept changes to fix the bug, as it can take a long time for Mojang to fix 25 | them (sometimes years). If an issue gets declined by Mojang, we normally do not "fix" it as it is intended behavior. 26 | 27 | ## Duplication bugs 28 | 29 | Because TNT duping is considered a form of automated mining and not a resource dupe, we have provided an option to 30 | restore it. This, undesirably, also re-enables carpet and rail duping, which normally we would not provide a config for, 31 | but it's the same bug for those, so we have no choice. However, the config option is as follows: 32 | 33 | ```yaml title="config/paper-global.yml" 34 | unsupported-settings: 35 | allow-piston-duplication: true 36 | ``` 37 | 38 | We also allow you to restore the ability to duplicate gravity blocks, such as sand, using end portals. This is not 39 | recommended, as it can cause issues with the server, but we do provide a config option to restore this functionality: 40 | ```yaml title="config/paper-global.yml" 41 | unsupported-settings: 42 | allow-unsafe-end-portal-teleportation: true 43 | ``` 44 | 45 | ## Block breaking 46 | 47 | We also fix the ability to break Bedrock and End Portal frames. We do also provide a config option to restore this 48 | functionality, but it is not recommended: 49 | ```yaml title="config/paper-global.yml" 50 | unsupported-settings: 51 | allow-permanent-block-break-exploits: true 52 | ``` 53 | 54 | ## Afterword 55 | 56 | We will not support you if you have issues whilst these settings are enabled, as they can cause unintended side effects. 57 | These settings are also not guaranteed to be supported in the future and may have their behavior changed, or removed, at any time. 58 | 59 | For legacy reasoning behind not having configuration options for many duplication bugs, see: 60 | [#3724](https://github.com/PaperMC/Paper/issues/3724) 61 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/assets/plugin-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/admin/reference/assets/plugin-list.png -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: commands.yml 3 | description: An explanation of Bukkit's commands.yml file. 4 | slug: paper/reference/bukkit-commands-configuration 5 | tableOfContents: false 6 | --- 7 | 8 | import ConfigNode from "/src/components/ConfigNode.astro"; 9 | import CommandsYML from "/src/config/paper/commands.yml?raw"; 10 | import { parse } from "yaml"; 11 | 12 | :::note 13 | 14 | The below YAML shows you the structure and default values for the legacy `commands.yml`. 15 | 16 | Click on a leaf node to view the description for that setting. 17 | 18 | ::: 19 | 20 | :::caution 21 | 22 | The aliases defined in this legacy file do not support modern features, such as: 23 | - Tab completion 24 | - Permissions 25 | 26 | ::: 27 | 28 | 29 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/bukkit-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: bukkit.yml 3 | description: An explanation of Bukkit's configuration file. 4 | slug: paper/reference/bukkit-configuration 5 | tableOfContents: false 6 | --- 7 | 8 | import ConfigNode from "/src/components/ConfigNode.astro"; 9 | import BukkitYML from "/src/config/paper/bukkit.yml?raw"; 10 | import { parse } from "yaml"; 11 | 12 | :::note 13 | 14 | The below YAML shows you the structure and default values for `bukkit.yml`. 15 | 16 | Click on a leaf node to view the description for that setting. 17 | 18 | ::: 19 | 20 | 21 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/bukkit-help-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: help.yml 3 | description: An explanation of Bukkit's help.yml file. 4 | slug: paper/reference/bukkit-help-configuration 5 | tableOfContents: false 6 | --- 7 | 8 | import ConfigNode from "/src/components/ConfigNode.astro"; 9 | import HelpYML from "/src/config/paper/help.yml?raw"; 10 | import { parse } from "yaml"; 11 | 12 | :::note 13 | 14 | The below YAML shows you the structure for `help.yml`. 15 | 16 | Click on a leaf node to view the description for that setting. 17 | 18 | ::: 19 | 20 | 21 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/bukkit-permissions-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: permissions.yml 3 | description: An explanation of Bukkit's permissions.yml file. 4 | slug: paper/reference/bukkit-permissions-configuration 5 | tableOfContents: false 6 | --- 7 | 8 | import ConfigNode from "/src/components/ConfigNode.astro"; 9 | import PermissionsYML from "/src/config/paper/permissions.yml?raw"; 10 | import { parse } from "yaml"; 11 | 12 | :::note 13 | 14 | The below YAML shows you the structure for `permissions.yml`. 15 | 16 | Click on a leaf node to view the description for that setting. 17 | 18 | ::: 19 | 20 | :::caution 21 | 22 | This is NOT a replacement for a permissions plugin. 23 | 24 | This file is used to define metadata about permissions themselves, including a description and a default value. 25 | 26 | ::: 27 | 28 | 29 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/global-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Global configuration 3 | description: An explanation of Paper's global configuration file. 4 | slug: paper/reference/global-configuration 5 | tableOfContents: false 6 | --- 7 | 8 | import ConfigNode from "/src/components/ConfigNode.astro"; 9 | import PaperGlobalYML from "/src/config/paper/paper-global.yml?raw"; 10 | import { parse } from "yaml"; 11 | 12 | :::note 13 | 14 | The below YAML shows you the structure and default values for the global configuration (`config/paper-global.yml`). 15 | 16 | Click on a leaf node to view the description for that setting. 17 | 18 | ::: 19 | 20 | 21 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/server-properties.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: server.properties 3 | description: An explanation of Minecraft's server.properties file. 4 | slug: paper/reference/server-properties 5 | tableOfContents: false 6 | --- 7 | 8 | import ConfigNode from "/src/components/ConfigNode.astro"; 9 | import ServerPropertiesYML from "/src/config/paper/server-properties.yml?raw"; 10 | import { parse } from "yaml"; 11 | 12 | :::note 13 | 14 | The below page shows the settings and default values for the `server.properties` file. 15 | 16 | Click on a property to learn more about it. 17 | 18 | ::: 19 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/spigot-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: spigot.yml 3 | description: An explanation of Spigot's configuration file. 4 | slug: paper/reference/spigot-configuration 5 | tableOfContents: false 6 | --- 7 | 8 | import ConfigNode from "/src/components/ConfigNode.astro"; 9 | import SpigotYML from "/src/config/paper/spigot.yml?raw"; 10 | import { parse } from "yaml"; 11 | 12 | :::note 13 | 14 | The below YAML shows you the structure and default values for `spigot.yml` 15 | 16 | Click on a leaf node to view the description for that setting. 17 | 18 | ::: 19 | 20 | :::note 21 | 22 | To override a per-world option, create a new key under `world-settings` with the level-name (name of the folder). 23 | 24 | ::: 25 | 26 | 27 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/vanilla-data-files.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Vanilla data files 3 | description: An explanation of Minecraft's data files. 4 | slug: paper/reference/vanilla-data-files 5 | --- 6 | 7 | import ConfigNode from "/src/components/ConfigNode.astro"; 8 | import { parse } from "yaml"; 9 | import EulaYML from "/src/config/paper/eula.yml?raw"; 10 | import BannedIpsYML from "/src/config/paper/banned-ips-single.yml?raw"; 11 | import BannedPlayersYML from "/src/config/paper/banned-players-single.yml?raw"; 12 | import OpsYML from "/src/config/paper/ops-single.yml?raw"; 13 | import WhitelistYML from "/src/config/paper/whitelist-single.yml?raw"; 14 | 15 | ## `eula.txt` 16 | 17 | `eula.txt` is a simple config file that allows you to accept the [EULA](https://aka.ms/MinecraftEULA), 18 | which is required to run the Minecraft server. 19 | 20 | 21 | 22 | ## `banned-ips.json` 23 | 24 | `banned-ips.json` is a JSON file that stores IP addresses that are not allowed to connect to the server. 25 | 26 | :::caution 27 | 28 | This is a data file used by the server, not a configuration file. 29 | 30 | We do not recommend editing this file directly, and this is provided for reference only. 31 | 32 | Instead, use the `/ban-ip`, `/pardon-ip`, and `/banlist ips` commands to manage banned-ips.json. 33 | 34 | ::: 35 | 36 | 37 | 38 | 39 | ## `banned-players.json` 40 | 41 | `banned-players.json` is a JSON file that stores players that are not allowed to connect to the server. 42 | 43 | :::caution 44 | 45 | This is a data file used by the server, not a configuration file. 46 | 47 | We do not recommend editing this file directly, and this is provided for reference only. 48 | 49 | Instead, use the `/ban`, `/pardon`, and `/banlist players` commands to manage banned-players.json. 50 | 51 | ::: 52 | 53 | 54 | 55 | ## `ops.json` 56 | 57 | `ops.json` is a JSON file that stores player's operator status information. 58 | 59 | In Vanilla, this is used as a rudimentary permissions system, and to allow certain player to bypass the player limit. 60 | 61 | :::caution 62 | 63 | This is a data file used by the server, not a configuration file. 64 | 65 | We do not recommend editing this file directly, and this is provided for reference only. 66 | 67 | Instead, use the `/op`, `/deop` commands to manage ops.json. 68 | 69 | ::: 70 | 71 | 72 | 73 | ## `whitelist.json` 74 | 75 | `whitelist.json` is a JSON file that stores players that are allowed to connect to the server. 76 | 77 | It is used in conjunction with the [`white-list`](/paper/reference/server-properties#white_list) option in `server.properties`. 78 | 79 | 80 | :::caution 81 | 82 | This is a data file used by the server, not a configuration file. 83 | 84 | We do not recommend editing this file directly, and this is provided for reference only. 85 | 86 | Instead, use the `/whitelist` command to manage whitelist.json. 87 | 88 | ::: 89 | 90 | 91 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/configuration/world-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: World configuration 3 | slug: paper/reference/world-configuration 4 | description: An explanation of Paper's world configuration file. 5 | tableOfContents: false 6 | --- 7 | 8 | import ConfigNode from "/src/components/ConfigNode.astro"; 9 | import PaperWorldDefaultsYML from "/src/config/paper/paper-world-defaults.yml?raw"; 10 | import { parse } from "yaml"; 11 | 12 | :::note 13 | 14 | The below YAML shows you the structure and default values for the world configuration (`config/paper-world-defaults.yml` and `/paper-world.yml`). 15 | 16 | Click on a leaf node to view the description for that setting. 17 | 18 | ::: 19 | 20 | 21 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Reference 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Reference of Paper's configuration options, system properties and other features. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/paper/admin/reference/paper-plugins.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Paper plugins 3 | description: A guide to the ins and outs of Paper plugins. 4 | slug: paper/reference/paper-plugins 5 | --- 6 | 7 | This documentation page serves to explain all the new semantics and possible confusions that Paper plugins may introduce. 8 | 9 | :::note 10 | 11 | Developers can get more information on Paper plugins [here](/paper/dev/getting-started/paper-plugins). 12 | 13 | ::: 14 | 15 | ## What are they? 16 | 17 | Paper plugins are plugins which are loaded by Paper's new plugin loading framework. Paper plugins are used by developers to 18 | take advantage of modern systems Mojang provides, for example, datapacks. 19 | 20 | ![Plugin List](./assets/plugin-list.png) 21 | 22 | ## What is the difference? 23 | 24 | When enabled, Paper plugins are **identical** to Bukkit plugins. This allows plugins to still fully communicate and support each other, meaning that even if a 25 | plugin is a Bukkit or Paper plugin, they are both able to depend on each other just fine. 26 | 27 | Paper plugins only support being loaded by Paper's Plugin Loader and may use new API unavailable to Bukkit plugins. 28 | 29 | ### How do I add Paper plugins? 30 | 31 | Paper plugins are added the same as Bukkit plugins, therefore, you can follow [this guide](/paper/adding-plugins). 32 | 33 | ### Cyclic plugin loading 34 | 35 | With the introduction of Paper plugins, Paper introduces a new plugin loader that fixes some odd issues. 36 | However, as a result, this now causes [cyclic loading](/paper/dev/getting-started/paper-plugins#cyclic-plugin-loading) between plugins to no longer be supported. 37 | 38 | If Paper detects a loop, your server will be shut down with an error. 39 | 40 | :::danger[Legacy] 41 | 42 | If your server **requires** this circular loading, you can enable this by adding the [`-Dpaper.useLegacyPluginLoading=true`](/paper/reference/system-properties#paperuselegacypluginloading) startup flag. 43 | Please note that this may not be supported in the future. 44 | 45 | ::: 46 | -------------------------------------------------------------------------------- /src/content/docs/paper/contributing/events.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Events 3 | description: A guide on how to add new events to Paper. 4 | slug: paper/contributing/events 5 | --- 6 | 7 | There are several requirements for events in the Paper API. 8 | 9 | :::note 10 | 11 | Note that while not all existing events may follow these 12 | guidelines, all new and modified events should adhere to them. 13 | 14 | ::: 15 | 16 | All new events should go in the package (sub-package of) `io.papermc.paper.event`. 17 | 18 | ### Constructors 19 | 20 | All new constructors added should be annotated with 21 | [`@ApiStatus.Internal`](https://javadoc.io/doc/org.jetbrains/annotations/latest/org/jetbrains/annotations/ApiStatus.Internal.html) 22 | to signify that they are not considered API and can change at any time without warning. 23 | 24 | Constructors that are being replaced, if they aren't being removed, should be marked with 25 | [`@Deprecated`](jd:java:java.lang.Deprecated) and [`@DoNotUse`](jd:paper:io.papermc.paper.annotation.DoNotUse). 26 | 27 | ### Mutability 28 | Certain API types are "mutable" which can lead to unexpected behavior within events. Mutable types like 29 | [`Location`](jd:paper:org.bukkit.Location) and [`Vector`](jd:paper:org.bukkit.util.Vector) 30 | should therefore be cloned when returned from a "getter" in an event. 31 | 32 | ### `HandlerList` 33 | For an event class or any subclass of it to be listened to, a [`HandlerList`](jd:paper:org.bukkit.event.HandlerList) 34 | field must be present with an instance and static method to retrieve it. 35 | See the docs for [`Event`](jd:paper:org.bukkit.event.Event) for specifics. 36 | This field should be static and final and named `HANDLER_LIST`. 37 | 38 | Also consider not putting a `HandlerList` on every event, just a "common parent" event so that a plugin can listen to the 39 | parent event and capture any child events but also listen to the child event separately. 40 | 41 | ### Miscellaneous 42 | 43 | * New parameters or method returns of type [`ItemStack`](jd:paper:org.bukkit.inventory.ItemStack) 44 | should not be [`@Nullable`](https://javadoc.io/doc/org.jspecify/jspecify/latest/org/jspecify/annotations/Nullable.html) 45 | in most case and instead accept an empty itemStack. 46 | -------------------------------------------------------------------------------- /src/content/docs/paper/contributing/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contributing 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Welcome to the Paper contributing guide! This guide includes information and tutorials for developers 9 | wishing to contribute to the Paper project. 10 | 11 | 12 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/assets/data-component-api-tree.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/assets/data-component-api-tree.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/enchants-registry.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/enchants-registry.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-attributes.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-attributes.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-banner-pattern.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-banner-pattern.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-biome.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-biome.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-block.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-block.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-cat-variant.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-cat-variant.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-chicken-variant.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-chicken-variant.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-cow-variant.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-cow-variant.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-damage-type.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-damage-type.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-data-component-type.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-data-component-type.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-enchantment.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-enchantment.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-entity-type.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-entity-type.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-fluid.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-fluid.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-frog-variant.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-frog-variant.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-game-event.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-game-event.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-instrument.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-instrument.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-item.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-item.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-jukebox-song.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-jukebox-song.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-map-decoration-type.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-map-decoration-type.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-memory-module-type.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-memory-module-type.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-menu.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-menu.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-mob-effect.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-mob-effect.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-painting-variant.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-painting-variant.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-particle-type.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-particle-type.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-pig-variant.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-pig-variant.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-potion.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-potion.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-sound-event.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-sound-event.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-structure-type.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-structure-type.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-material.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-material.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-pattern.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-pattern.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-profession.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-profession.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-type.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-type.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-wolf-sound-variant.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-wolf-sound-variant.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-wolf-variant.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-wolf-variant.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resourcekey-item.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resourcekey-item.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockposition.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockposition.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockstate.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockstate.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/component.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/component.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/doublerange.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/doublerange.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entities.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entities.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-opped.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-opped.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-unopped.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-unopped.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entityanchor.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entityanchor.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/fineposition.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/fineposition.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/gamemode.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/gamemode.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/heightmap.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/heightmap.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/integerrange.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/integerrange.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itempredicate.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itempredicate.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itemstack.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itemstack.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/key.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/key.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namedcolor.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namedcolor.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namespacedkey.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namespacedkey.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/objectivecriteria.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/objectivecriteria.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/player.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/player.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/playerprofiles.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/playerprofiles.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/players.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/players.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/scoreboarddisplayslot.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/scoreboarddisplayslot.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/signedmessage.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/signedmessage.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/style.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/style.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templatemirror.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templatemirror.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templaterotation.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templaterotation.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/time.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/time.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/uuid.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/uuid.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/world.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/world.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/arguments/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Arguments 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | 9 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/big-float.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/big-float.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/client-server-mismatch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/client-server-mismatch.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/flyspeed-console.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/flyspeed-console.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/flyspeed-player.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/flyspeed-player.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/flyspeed-proxied.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/flyspeed-proxied.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/forest/tree-descriptions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/forest/tree-descriptions.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/forest/tree.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/forest/tree.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/give-item-command.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/give-item-command.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/ice-cream-invalid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/ice-cream-invalid.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/ice-cream.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/ice-cream.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/select-name-command.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/select-name-command.mp4 -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/small-float.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/small-float.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/string-arguments.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/string-arguments.gif -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/suggestion-tooltip.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/suggestion-tooltip.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/assets/valid-float.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/basics/assets/valid-float.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Basics 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | 9 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/introduction.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Introduction 3 | description: A guide to Paper's Brigadier command API. 4 | slug: paper/dev/command-api/basics/introduction 5 | --- 6 | 7 | Paper's command system is built on top of Minecraft's Brigadier command system. This system provides a powerful and flexible way to define commands and arguments. 8 | It offers many advantages above the previously widely used Bukkit command system: 9 | - Less parsing or error checking required by the developer for arguments. 10 | - Better user experience with client error checking. 11 | - Integration with reload events, allowing the definition of commands usable in datapacks. 12 | - Easier creation of subcommands. 13 | 14 | :::danger[Experimental] 15 | 16 | Paper's command system is still experimental and may change in the future. 17 | 18 | ::: 19 | 20 | :::note 21 | 22 | To see a comparison between the new Brigadier system and the old Bukkit system, [click here](/paper/dev/command-api/misc/comparison-bukkit-brigadier). 23 | 24 | ::: 25 | 26 | ## Guide 27 | The following sites are worth-while to look through first when learning about Brigadier: 28 | - [The Command Tree](/paper/dev/command-api/basics/command-tree) 29 | - [Arguments and Literals](/paper/dev/command-api/basics/arguments-and-literals) 30 | - [Command Executors](/paper/dev/command-api/basics/executors) 31 | - [Command Registration](/paper/dev/command-api/basics/registration) 32 | - [Command Requirements](/paper/dev/command-api/basics/requirements) 33 | - [Argument Suggestions](/paper/dev/command-api/basics/argument-suggestions) 34 | - [Custom Arguments](/paper/dev/command-api/basics/custom-arguments) 35 | 36 | For a reference of more advanced arguments, you should look here: 37 | - [Minecraft Arguments](/paper/dev/command-api/arguments/minecraft) 38 | 39 | :::danger[Future pages] 40 | 41 | The following pages will be added to the documentation in the future: 42 | 43 | - **Tutorial: Creating Utility Commands** 44 | - **The Command Dispatcher** 45 | - **Forks and Redirects** 46 | - **Tutorial: Extending the vanilla execute command** 47 | 48 | ::: 49 | 50 | ## Additional support 51 | For support regarding the command API, you can always ask in our [Discord server](https://discord.gg/PaperMC) under the 52 | [`#paper-dev`](https://discord.com/channels/289587909051416579/555462289851940864) channel! 53 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/basics/requirements.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Requirements 3 | description: A guide to setting requirements for commands. 4 | slug: paper/dev/command-api/basics/requirements 5 | --- 6 | 7 | Sometimes you want to limit a player's ability to use and/or view certain commands or subcommands. Exactly for this purpose, 8 | the `ArgumentBuilder` class has a `requires(Predicate)` method to define a requirement in order to use that specific branch of a command tree. 9 | As always, the generic parameter `S` is just a `CommandSourceStack`, providing us with the executing entity, the command sender, and the location of the command. 10 | 11 | ## Defining permissions 12 | One of the most common usecases for requirements are permissions. Usually, these are checked on the **command sender**, as that is the actual entity/console/object 13 | which ran the command, even if it is run as someone else (the executor). A simple command with a permission might look like this: 14 | 15 | ```java 16 | Commands.literal("testcmd") 17 | .requires(sender -> sender.getSender().hasPermission("permission.test")) 18 | .executes(ctx -> { 19 | ctx.getSource().getSender().sendRichMessage("You have permission to run this command!"); 20 | return Command.SINGLE_SUCCESS; 21 | }); 22 | ``` 23 | 24 | This command requires the `permission.test` permission to be had by a sender. 25 | But you cannot only define permissions, you can also require a sender to be a server operator, like this: 26 | 27 | ```java 28 | Commands.literal("testcmd") 29 | .requires(sender -> sender.getSender().isOp()) 30 | .executes(ctx -> { 31 | ctx.getSource().getSender().sendRichMessage("You are a server operator!"); 32 | return Command.SINGLE_SUCCESS; 33 | }); 34 | ``` 35 | 36 | ## Defining more advanced predicates 37 | You don't have to limit yourself to checking just for permissions - since it is a predicate, any boolean can be returned. For example, you can check for whether 38 | a player has a diamond sword in their inventory: 39 | 40 | ```java 41 | Commands.literal("givesword") 42 | .requires(sender -> sender.getExecutor() instanceof Player player && !player.getInventory().contains(Material.DIAMOND_SWORD)) 43 | .executes(ctx -> { 44 | if (ctx.getSource().getExecutor() instanceof Player player) { 45 | player.getInventory().addItem(ItemType.DIAMOND_SWORD.createItemStack()); 46 | } 47 | 48 | return Command.SINGLE_SUCCESS; 49 | }); 50 | ``` 51 | 52 | At first glance, this works just fine. But it does have a very big flaw - since the player's client is not aware of the requirement, it still shows the command 53 | as executable, even if the requirement resolves as false. But if the client tries to run the command, the server reports that this command doesn't exist (meaning 54 | the requirement was not met): 55 | 56 | ![](./assets/client-server-mismatch.png) 57 | 58 | How can we solve this? The `Player` interface has a method called [`#updateCommands()`](jd:paper:org.bukkit.entity.Player#updateCommands()) just for this usecase. It resends the currently registered commands back to the 59 | client in an attempt to reload commands. For now, we can create a new command with which the player can update its own commands in order to resync its command state: 60 | 61 | ```java 62 | Commands.literal("reloadcommands") 63 | .executes(ctx -> { 64 | if (ctx.getSource().getExecutor() instanceof Player player) { 65 | player.updateCommands(); 66 | player.sendRichMessage("Successfully updated your commands!"); 67 | } 68 | 69 | return Command.SINGLE_SUCCESS; 70 | }); 71 | ``` 72 | 73 | ## Automating command reloads 74 | Forcing a player to reload their own commands is not a viable option for user experience. For this reason, you can **automate** this behavior. It is safe to call 75 | the update commands method as often as required, but it should generally be avoided as it can cost a great deal of bandwidth. If possible, you should instead place 76 | these in very specific spots. Furthermore, this method is completely thread safe, meaning you are free to call it from an asynchronous context. 77 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Command API 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | #### Basics 9 | 10 | 11 | 12 | #### Arguments 13 | 14 | 15 | 16 | #### Miscellaneous 17 | 18 | 19 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/misc/assets/broadcast-command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/misc/assets/broadcast-command.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/misc/assets/broadcast-suggestions-finished.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/misc/assets/broadcast-suggestions-finished.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/misc/assets/broadcast-suggestions-none.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/misc/assets/broadcast-suggestions-none.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/misc/assets/broadcast-suggestions-unfinished.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/misc/assets/broadcast-suggestions-unfinished.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/misc/assets/bukkitparty-command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/misc/assets/bukkitparty-command.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/misc/assets/paperparty-command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/command-api/misc/assets/paperparty-command.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/command-api/misc/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Miscellaneous 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | 9 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/component-api/audiences.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Audiences 3 | description: How to use Adventure's Audiences. 4 | slug: paper/dev/component-api/audiences 5 | --- 6 | 7 | Audiences wrap a collection of recipients that can receive messages. They can be used to send messages to individual 8 | players, groups of players, or even the entire server (including the console). 9 | 10 | ## Who is an `Audience`? 11 | 12 | All `CommandSender`s are single audiences. This includes players, the console, and command blocks. `Server`, `Team` and 13 | `World` are all forwarding audiences. This means that they are made up of multiple audiences. For example, the server is 14 | made up of all online players and the console. 15 | 16 | This means that all the [`Audience`](https://jd.advntr.dev/api/latest/net/kyori/adventure/audience/Audience.html) 17 | methods are available on [`CommandSender`](jd:paper:org.bukkit.command.CommandSender), 18 | [`Server`](jd:paper:org.bukkit.Server), [`Team`](jd:paper:org.bukkit.scoreboard.Team) 19 | and [`World`](jd:paper:org.bukkit.World). 20 | 21 | ## `ForwardingAudience` 22 | 23 | The [`ForwardingAudience`](https://jd.advntr.dev/api/latest/net/kyori/adventure/audience/ForwardingAudience.html) 24 | wraps a collection of [`Audience`](https://jd.advntr.dev/api/latest/net/kyori/adventure/audience/Audience.html) 25 | instances and forwards messages to all of them. This is useful for sending messages to multiple audiences (players) at once. 26 | 27 | ```java 28 | // Server is a ForwardingAudience which includes all online players and the console 29 | ForwardingAudience audience = Bukkit.getServer(); 30 | 31 | // To construct an audience from a collection of players, use: 32 | Audience audience = Audience.audience(Audience...); 33 | // If you pass in a single Audience, it will be returned as-is. If you pass in a collection of Audiences, they will be 34 | // wrapped in a ForwardingAudience. 35 | ``` 36 | 37 | ## What do `Audience`s do? 38 | 39 | Audiences are used for interacting with players. They can be used to send messages, play sounds, show bossbars, and more. 40 | They are mostly used for sending other parts of the API to players. For example, you can send a [`Component`](https://jd.advntr.dev/api/latest/net/kyori/adventure/text/Component.html) 41 | to a player using [`Audience#sendMessage(Component)`](https://jd.advntr.dev/api/latest/net/kyori/adventure/audience/Audience.html#sendMessage(net.kyori.adventure.text.Component)). 42 | 43 | ## Pointers 44 | 45 | Audiences can also provide arbitrary information, such as display name or UUID. This is done using the pointer system. 46 | 47 | ```java 48 | // Get the uuid from an audience member, returning an Optional 49 | Optional uuid = audience.get(Identity.UUID); 50 | 51 | // Get the display name, returning a default 52 | Component name = audience.getOrDefault(Identity.DISPLAY_NAME, Component.text("no display name!")); 53 | ``` 54 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/component-api/i18n.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Internationalization 3 | description: How to use Adventure's internationalization. 4 | slug: paper/dev/component-api/i18n 5 | --- 6 | 7 | Generally it's a good idea to support translations in your plugin, especially if you want to 8 | appeal to the largest user base. Adventure makes this simple by adding a server-side 9 | translation layer to almost all text that ends up being displayed to clients. 10 | 11 | :::note[Javadocs] 12 | 13 | Adventure's Javadocs for all-things translations can be found [here](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/package-summary.html). 14 | 15 | ::: 16 | 17 | ## GlobalTranslator 18 | 19 | All translation is done through [`GlobalTranslator`](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/GlobalTranslator.html). 20 | You can render translations yourself and add new sources for translations. 21 | 22 | You can add sources to the `GlobalTranslator` by creating instances of [`TranslationStore`](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/TranslationStore.html) 23 | or implementing the [`Translator`](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/Translator.html) interface yourself. 24 | 25 | ## Where translations work 26 | 27 | Vanilla Minecraft handles translations on the client by using the language files bundled with the client or provided via resource packs. If you don't want to send custom language files 28 | in a resource pack, server-side translations are the only alternative. They work anywhere the component API exists, except for [`ItemStack`](jd:paper:org.bukkit.inventory.ItemStack) 29 | display text like the display name or lore. So chat, entity display names, scoreboards, tab lists, etc., all support translations. 30 | 31 | ## Examples 32 | 33 | ### `ResourceBundle` 34 | ```properties title="src/main/resources/your/plugin/Bundle_en_US.properties" 35 | some.translation.key=Translated Message: {0} 36 | ``` 37 | 38 | ```java 39 | TranslationStore.StringBased store = TranslationStore.messageFormat(Key.key("namespace:value")); 40 | 41 | ResourceBundle bundle = ResourceBundle.getBundle("your.plugin.Bundle", Locale.US, UTF8ResourceBundleControl.get()); 42 | store.registerAll(Locale.US, bundle, true); 43 | GlobalTranslator.translator().addSource(store); 44 | ``` 45 | 46 | This creates a new `TranslationStore` under a specified namespace. Then, a [`ResourceBundle`](jd:java:java.util.ResourceBundle) 47 | is created from a bundle located on the classpath with the specified [`Locale`](jd:java:java.util.Locale). 48 | Finally, that `ResourceBundle` is added to the store. That store is then added as a source to the `GlobalTranslator`. 49 | This makes all the translations available server-side. 50 | 51 | Now you can use your translation keys in translatable components. 52 | 53 | ```java 54 | Component.translatable("some.translation.key", Component.text("The Argument")) 55 | ``` 56 | 57 | This will show to clients using the US English language: `Translated Message: The Argument`. 58 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/component-api/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Component API 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | 9 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/entity-api/assets/display-interp.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/entity-api/assets/display-interp.gif -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/entity-api/assets/display-rotation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/entity-api/assets/display-rotation.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/entity-api/assets/display-scale.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/entity-api/assets/display-scale.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/entity-api/assets/display-trans.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/entity-api/assets/display-trans.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/entity-api/entity-teleport.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Teleportation 3 | description: The entity teleportation API and how to use it. 4 | slug: paper/dev/entity-teleport 5 | --- 6 | 7 | Entities can be instantaneously teleported to specific positions, synchronously and asynchronously with the 8 | [`teleport`](jd:paper:org.bukkit.entity.Entity#teleport(org.bukkit.Location)) and 9 | [`teleportAsync`](jd:paper:org.bukkit.entity.Entity#teleportAsync(org.bukkit.Location)) API. 10 | 11 | :::tip[Performance] 12 | 13 | If you expect to teleport into unloaded chunks, it is recommended to use the `teleportAsync` API, 14 | as it avoids doing synchronous chunk loads, which put a lot of stress on the server's main thread - 15 | hurting overall performance. 16 | 17 | ::: 18 | 19 | ```java 20 | entity.teleport(location); // loads chunks synchronously and teleports the entity 21 | 22 | entity.teleportAsync(location).thenAccept(success -> { // loads chunks asynchronously and teleports the entity 23 | // this code is ran when the teleport completes 24 | // the Future is completed on the main thread, so it is safe to use the API here 25 | 26 | if (success) { 27 | // the entity was teleported successfully! 28 | } 29 | }); 30 | ``` 31 | 32 | :::danger 33 | 34 | You should **NEVER** call `.get()`/`.join()` on the `teleportAsync` `Future` on the main thread, 35 | as it **WILL** deadlock your server, if the chunk you're teleporting into is not loaded. 36 | 37 | ::: 38 | 39 | ## Look at 40 | 41 | The [`lookAt`](jd:paper:org.bukkit.entity.Player#lookAt(org.bukkit.entity.Entity,io.papermc.paper.entity.LookAnchor,io.papermc.paper.entity.LookAnchor)) 42 | API allows you to make a player look at a certain position or entity. 43 | 44 | ```java 45 | player.lookAt( 46 | position, 47 | LookAnchor.EYES // the player's eyes will be facing the position 48 | ); 49 | 50 | player.lookAt( 51 | entity, 52 | LookAnchor.EYES // the player's eyes will be facing the entity 53 | LookAnchor.FEET // the player will be facing the entity's feet 54 | ); 55 | ``` 56 | 57 | ## Teleport flags 58 | 59 | Teleport flags offer a way to teleport entities whilst being able to customize behavior. 60 | This allows you to do things like teleport players using relative flags and being able to retain passengers. 61 | 62 | All available teleport flags can be found in the [`TeleportFlag`](jd:paper:io.papermc.paper.entity.TeleportFlag) class. 63 | 64 | ### Relative teleportation 65 | 66 | Teleport a player relatively, preventing velocity from being reset in the X, Y and Z axes. 67 | 68 | ```java 69 | player.teleport( 70 | location, 71 | TeleportFlag.Relative.VELOCITY_X, 72 | TeleportFlag.Relative.VELOCITY_Y, 73 | TeleportFlag.Relative.VELOCITY_Z 74 | ); 75 | ``` 76 | 77 | ### Retaining passengers 78 | 79 | Teleport an entity with the [`RETAIN_PASSENGERS`](jd:paper:io.papermc.paper.entity.TeleportFlag$EntityState#RETAIN_PASSENGERS) flag, 80 | allowing its passengers to be transferred with the entity. 81 | 82 | ```java 83 | entity.teleport(location, TeleportFlag.EntityState.RETAIN_PASSENGERS); 84 | ``` 85 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/entity-api/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Entity API 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | 9 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/event-api/assets/plain-message-rendering.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/event-api/assets/plain-message-rendering.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/event-api/assets/prefix-rendering.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/api/event-api/assets/prefix-rendering.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/event-api/handler-lists.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Handler lists 3 | description: An explanation to what an event's HandlerList is. 4 | slug: paper/dev/handler-lists 5 | --- 6 | 7 | Every [`Event`](jd:paper:org.bukkit.event.Event) that can be listened to has a 8 | [`HandlerList`](jd:paper:org.bukkit.event.HandlerList) containing all the listeners that are listening to that event. 9 | This list is used to call the listeners when the event is called. 10 | 11 | ## Getting the handler list for an event 12 | 13 | To get the handler list for an event, you can call `getHandlerList()` on the specific event class. 14 | 15 | ```java title="ExampleListener.java" 16 | public class ExampleListener implements Listener { 17 | 18 | @EventHandler 19 | public void onPlayerJoin(PlayerJoinEvent event) { 20 | HandlerList handlerList = event.getHandlerList(); 21 | // ... 22 | } 23 | 24 | // Or: 25 | 26 | public ExampleListener() { 27 | // Access the handler list through the static getter 28 | HandlerList handlerList = PlayerJoinEvent.getHandlerList(); 29 | // ... 30 | } 31 | } 32 | ``` 33 | 34 | ## Unregistering a listener 35 | 36 | To unregister a listener, you can call `unregister()` on the `HandlerList` that the listener is registered to. 37 | 38 | ```java title="ExampleListener.java" 39 | public class ExampleListener implements Listener { 40 | 41 | @EventHandler 42 | public void onPlayerJoin(PlayerJoinEvent event) { 43 | HandlerList handlerList = event.getHandlerList(); 44 | handlerList.unregister(this); 45 | // ... 46 | } 47 | 48 | // Or: 49 | 50 | public ExampleListener() { 51 | // Access the handler list through the static getter 52 | HandlerList handlerList = PlayerJoinEvent.getHandlerList(); 53 | handlerList.unregister(this); 54 | // Granted this is a pretty stupid example... 55 | } 56 | } 57 | ``` 58 | 59 | You can unregister based on [`Listener`](jd:paper:org.bukkit.event.Listener) 60 | or [`Plugin`](jd:paper:org.bukkit.plugin.Plugin) for more convenience. 61 | Likewise, you can also unregister all listeners for a specific event by calling 62 | [`unregisterAll()`](jd:paper:org.bukkit.event.HandlerList#unregisterAll()) on the `HandlerList`. 63 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/event-api/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Event API 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | 9 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/folia-support.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Supporting Paper and Folia 3 | description: How to support both Folia and Paper within your plugin. 4 | slug: paper/dev/folia-support 5 | --- 6 | 7 | ![](https://assets.papermc.io/brand/folia.png) 8 | 9 | [Folia](https://github.com/PaperMC/Folia) is a fork of Paper, which is currently maintained by the PaperMC team. 10 | It adds the ability to split the world into regions as outlined [here](/folia/reference/overview) in more depth. 11 | 12 | # Checking for Folia 13 | 14 | Depending on what platform your plugin is running on, you may need to implement features differently. For this, you can 15 | use this utility method to check if the current server is running Folia: 16 | 17 | ```java 18 | private static boolean isFolia() { 19 | try { 20 | Class.forName("io.papermc.paper.threadedregions.RegionizedServer"); 21 | return true; 22 | } catch (ClassNotFoundException e) { 23 | return false; 24 | } 25 | } 26 | ``` 27 | 28 | ## Schedulers 29 | 30 | In order to support Paper and Folia, you must use the correct scheduler. Folia has different types of schedulers 31 | that can be used for different things. They are: 32 | 33 | - [Global](#global-scheduler) 34 | - [Region](#region-scheduler) 35 | - [Async](#async-scheduler) 36 | - [Entity](#entity-scheduler) 37 | 38 | If you use these schedulers when running Paper, they will be internally handled to provide the same functionality as if you were 39 | running Folia. 40 | 41 | ### Global scheduler 42 | The tasks that you run on the global scheduler will be executed on the global region, see [here](/folia/reference/overview#global-region) for 43 | more information. You should use this scheduler for any tasks that do not belong to any particular region. These can be fetched with: 44 | ```java 45 | GlobalRegionScheduler globalScheduler = server.getGlobalRegionScheduler(); 46 | ``` 47 | 48 | ### Region scheduler 49 | The region scheduler will be in charge of running tasks for the region that owns a certain location. Do not use this scheduler for 50 | operations on entities, as this scheduler is tied to the region. Each entity has its [own scheduler](#entity-scheduler) 51 | which will follow it across regions. As an example, let's say I want to set a block to a beehive: 52 | ```java 53 | Location locationToChange = ...; 54 | RegionScheduler scheduler = server.getRegionScheduler(); 55 | 56 | scheduler.execute(plugin, locationToChange, () -> { 57 | locationToChange.getBlock().setType(Material.BEEHIVE); 58 | }); 59 | ``` 60 | 61 | We pass the location as a parameter to the [`RegionScheduler`](jd:paper:io.papermc.paper.threadedregions.scheduler.RegionScheduler) 62 | as it needs to work out which region to execute on. 63 | 64 | ### Async scheduler 65 | The async scheduler can be used for running tasks independent of the server tick process. This can be fetched with: 66 | ```java 67 | AsyncScheduler asyncScheduler = server.getAsyncScheduler(); 68 | ``` 69 | 70 | ### Entity scheduler 71 | Entity schedulers are used for executing tasks on an entity. These will follow the entity wherever it goes, so you must use 72 | these instead of the region schedulers. 73 | ```java 74 | EntityScheduler scheduler = entity.getScheduler(); 75 | ``` 76 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: API 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Welcome to the Paper API guide! 9 | This guide includes information for developers about how to use specific parts of the Paper API. 10 | 11 | 12 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/api/recipes.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Recipes 3 | description: How to create and manage recipes. 4 | slug: paper/dev/recipes 5 | --- 6 | 7 | Recipes are a way to define a way to craft a particular item. They are defined by a plugin or 8 | datapack, however we are only going to cover the plugin side of things here. 9 | 10 | ## [`ShapedRecipe`](jd:paper:org.bukkit.inventory.ShapedRecipe) 11 | 12 | A shaped recipe is a recipe that requires a specific pattern of items in the crafting grid to craft an item. 13 | These are created using a pattern string and a map of characters to items. The pattern strings are 3, 14 | 3-character strings that represent the rows of the crafting grid. They can be created as follows: 15 | 16 | ```java title="TestPlugin.java" 17 | public class TestPlugin extends JavaPlugin { 18 | 19 | @Override 20 | public void onEnable() { 21 | NamespacedKey key = new NamespacedKey(this, "WarriorSword"); 22 | ItemStack item = ItemStack.of(Material.DIAMOND_SWORD); 23 | 24 | ShapedRecipe recipe = new ShapedRecipe(key, item); 25 | recipe.shape(" A ", "AAA", " B "); 26 | recipe.setIngredient('A', Material.DIAMOND); 27 | recipe.setIngredient('B', Material.STICK); 28 | 29 | getServer().addRecipe(recipe); 30 | } 31 | } 32 | ``` 33 | 34 | This recipe would require a diamond sword to be crafted with a diamond in the top row, a stick in 35 | the middle row, and a diamond in the bottom row. The diamond sword would be in the middle column of 36 | the bottom row. The result would look like this in the crafting grid: 37 | 38 | ``` 39 | A 40 | AAA 41 | B 42 | ``` 43 | 44 | :::note 45 | 46 | You do not need to register the recipe within your plugin's `onEnable` method, You can register it 47 | at any time. However, if you do not register it after the plugin has been enabled and there are 48 | players online, you will need to either resend all the recipes to the players or use the boolean 49 | parameter in the [`addRecipe`](jd:paper:org.bukkit.Server#addRecipe(org.bukkit.inventory.Recipe,boolean)) 50 | method to update all players with the new recipe. 51 | 52 | ::: 53 | 54 | :::caution 55 | 56 | You cannot use Air as a material in a shaped recipe, this will cause an error. 57 | 58 | ::: 59 | 60 | 61 | ## [`ShapelessRecipe`](jd:paper:org.bukkit.inventory.ShapelessRecipe) 62 | 63 | A shapeless recipe is a recipe that requires a specific number of items in the crafting grid to craft an item. 64 | These are created using a list of items. They can be created as follows: 65 | 66 | ```java title="TestPlugin.java" 67 | public class TestPlugin extends JavaPlugin { 68 | 69 | @Override 70 | public void onEnable() { 71 | NamespacedKey key = new NamespacedKey(this, "WarriorSword"); 72 | ItemStack item = ItemStack.of(Material.DIAMOND_SWORD); 73 | 74 | ShapelessRecipe recipe = new ShapelessRecipe(key, item); 75 | recipe.addIngredient(3, Material.DIAMOND); 76 | recipe.addIngredient(2, Material.STICK); 77 | 78 | getServer().addRecipe(recipe); 79 | } 80 | } 81 | ``` 82 | 83 | This recipe declares that you simply need 3 diamonds and 2 sticks to craft the item, without any specific 84 | orientation of the cross pattern in the crafting grid. This could be crafted in any of the following ways: 85 | ``` 86 | DSS | SDS | S D 87 | D | D | D 88 | D | D | D S 89 | ``` 90 | And, any other composition of the 5 items. 91 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/getting-started/assets/installing-plugin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/getting-started/assets/installing-plugin.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/getting-started/assets/new-project-paper.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/getting-started/assets/new-project-paper.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/getting-started/assets/paper-plugin-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/getting-started/assets/paper-plugin-overview.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/getting-started/assets/restart-ide.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/getting-started/assets/restart-ide.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/getting-started/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting started 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Welcome to the Paper development guide! This guide includes information and tutorials on 9 | how to start developing plugins for Paper. 10 | 11 | 12 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Development 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Welcome to the Paper development guide! This guide includes information and tutorials for developers 9 | on how to create and expand on Paper plugins. 10 | 11 | #### Getting started 12 | 13 | 14 | 15 | #### API 16 | 17 | 18 | 19 | #### Miscellaneous 20 | 21 | 22 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/misc/assets/add_breakpoints.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/misc/assets/add_breakpoints.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/misc/assets/config_add.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/misc/assets/config_add.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/misc/assets/config_dropdown.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/misc/assets/config_dropdown.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/misc/assets/debugger_connect.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/misc/assets/debugger_connect.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/misc/assets/debugger_use.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/paper/dev/misc/assets/debugger_use.png -------------------------------------------------------------------------------- /src/content/docs/paper/dev/misc/debugging.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Debugging your plugin 3 | description: Debugging is common when writing code. This guide outlines the common ways to debug your plugin. 4 | slug: paper/dev/debugging 5 | --- 6 | 7 | Debugging your plugin is vital to being able to fix bugs and issues in your plugin. This page will cover some of the most common debugging techniques. 8 | 9 | ## Printing to the console 10 | 11 | One of the most common debugging techniques is to print to the console. This is likely something you've done before, as it's very simple. 12 | This has a few downsides, though. It can be hard to find the print statements in the console, and it can be hard to remove them all when you're done debugging. Most notably, you have to recompile your plugin and restart the server to add or remove debugging. 13 | 14 | When debugging, you can use `System.out.println("");` to print to the console. It is recommended to use your plugin's logger instead though, 15 | as it will be easier to know which plugin the log has come from. This can be done simply with: 16 | 17 | ```java 18 | plugin.getComponentLogger().debug(Component.text("SuperDuperBad Thing has happened")); 19 | ``` 20 | 21 | :::note[Logger Levels] 22 | 23 | In some consoles, using the `warning` level will print the message in different colors. 24 | This can be useful for finding your print statements in the console. 25 | 26 | ::: 27 | 28 | ## Using a remote debugger 29 | 30 | A debugger is a tool that allows you to pause your code at a certain point and inspect the values of variables. 31 | This can be very useful for finding out why your code isn't working as expected and also for finding out where your code is going wrong. 32 | 33 | ### Setting up the debugger 34 | 35 | To use a debugger, you need to set up your IDE to use it. This is different for each IDE, but for the sake of this guide, we will be using IntelliJ IDEA. 36 | 37 | To set up a debugger in IntelliJ, you need to create a new run configuration. 38 | You can do this by clicking the dropdown next to the run button and clicking `Edit Configurations...`: 39 | 40 | ![](./assets/config_dropdown.png) 41 | 42 | Then, click the `+` button in the top left and select `Remote JVM Debug`. You can then name the configuration whatever you want, and click `Apply`: 43 | 44 | ![](./assets/config_add.png) 45 | 46 | Finally, copy the command line arguments from the window, and paste these into your server's startup script. 47 | These will go after the `java` command and before `-jar`. Once you have done this, you can click `OK`. For example: 48 | 49 | ```shell replace 50 | java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar paper-\{LATEST_PAPER_RELEASE}.jar nogui 51 | ``` 52 | 53 | Once your server is running, you can use the bug icon in the top right to connect your debugger to the server: 54 | 55 | ![](./assets/debugger_connect.png) 56 | 57 | #### Using the debugger 58 | 59 | Let's say we have this code: 60 | 61 | ```java 62 | @EventHandler 63 | public void onPlayerMove(PlayerMoveEvent event) { 64 | Player player = event.getPlayer(); 65 | Location location = player.getLocation(); 66 | 67 | if (location.getWorld() == null) 68 | return; 69 | 70 | if (location.getWorld().getEnvironment() == World.Environment.NETHER) { 71 | player.sendMessage("You are in the nether!"); 72 | } 73 | } 74 | ``` 75 | 76 | You can add a breakpoint to the line by clicking on the line number: 77 | 78 | ![](./assets/add_breakpoints.png) 79 | 80 | This will pause the code when it reaches that line. You can then use the debugger to inspect the values of variables: 81 | 82 | ![](./assets/debugger_use.png) 83 | 84 | You can inspect the values of each of the variables in the current scope. 85 | You can also use the buttons in the top to step from one breakpoint to the next. 86 | If needed, you can also use the text box at the top to evaluate expressions for debugging purposes. 87 | 88 | ### Using direct debugging 89 | 90 | Direct debugging will allow you to run the server directly from your IDE, and will allow you to use breakpoints and step through your code. 91 | We can achieve this by using [JPenilla's Gradle plugin](https://github.com/jpenilla/run-task) to run the server directly from the IDE. 92 | See [here](https://github.com/jpenilla/run-task#basic-usage) for instructions on how to set up the plugin. 93 | -------------------------------------------------------------------------------- /src/content/docs/paper/dev/misc/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Miscellaneous 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | These guides are for helping developers with parts of the development process that don't fit into the other categories. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/paper/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Paper Documentation 3 | tableOfContents: false 4 | --- 5 | 6 | import { CardGrid, LinkCard } from "@astrojs/starlight/components"; 7 | 8 | Paper is a Minecraft: Java Edition game server, designed to greatly improve performance and offer more advanced features and API. 9 | 10 | 11 | 16 | 21 | 26 | 27 | -------------------------------------------------------------------------------- /src/content/docs/velocity/admin/getting-started/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting started 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Guides for getting started with running a Velocity proxy. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/velocity/admin/how-to/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: How-to guides 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | How-to guides for setting up specific features of Velocity and managing the proxy. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/velocity/admin/how-to/migration.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Migration guide 3 | description: How to migrate your proxy between different Velocity versions. 4 | slug: velocity/migration 5 | --- 6 | 7 | New to Velocity, or upgrading to a new version of Velocity? This page will briefly explore what you 8 | need to be aware of for a successful migration. 9 | 10 | ## Migrating from Velocity 1.0.x to Velocity 1.1.0 11 | 12 | Moving from Velocity 1.0.x to Velocity 1.1.0 should be as simple as just replacing the Velocity JAR 13 | and restarting the proxy. You may want to back up your `velocity.toml` and then delete the current 14 | `velocity.toml` and let Velocity regenerate it to add the new settings that Velocity 1.1.0 15 | introduces. 16 | -------------------------------------------------------------------------------- /src/content/docs/velocity/admin/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Administration 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Welcome to the Velocity administration guide! This guide includes information and tutorials 9 | regarding the administration of a Velocity proxy. 10 | 11 | #### Getting started 12 | 13 | 14 | 15 | #### How-to guides 16 | 17 | 18 | 19 | #### Reference 20 | 21 | 22 | -------------------------------------------------------------------------------- /src/content/docs/velocity/admin/reference/commands.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Built-in commands 3 | description: A list of the built-in commands with explanations. 4 | slug: velocity/built-in-commands 5 | --- 6 | 7 | Velocity includes a few commands in the core of the proxy by default. These commands were chosen 8 | based on how generally useful they are to most users. 9 | 10 | Of course, you can always install plugins to add more commands if you want. 11 | 12 | ## `/velocity` 13 | 14 | The `/velocity` command contains a number of subcommands to manage the proxy. 15 | 16 | ### `/velocity plugins` 17 | 18 | If the user has the `velocity.command.plugins` permission, they can view all the plugins currently 19 | active on the proxy using `/velocity plugins`, including the name, authors, and version. 20 | 21 | ### `/velocity info` 22 | 23 | If the user has the `velocity.command.info` permission, they can view information about the Velocity instance, 24 | such as the version of Velocity running on the proxy. 25 | 26 | ### `/velocity reload` 27 | 28 | If the user has the `velocity.command.reload` permission, the proxy will read and reconfigure itself 29 | from the `velocity.toml` on disk. If there are problems with parsing the file, no changes will be 30 | applied. 31 | 32 | ### `/velocity dump` 33 | 34 | If the user has the `velocity.command.dump` permission, they can use this command to get an 35 | anonymized dump of details on the proxy. This can be sent to the PaperMC Discord to help us provide 36 | support. 37 | 38 | ### `/velocity heap` 39 | 40 | :::caution 41 | 42 | This command generates a heap dump which contains detailed information about your Velocity instance 43 | which can be quite sensitive, be very careful to whom you share the generated heap dump. 44 | 45 | ::: 46 | 47 | If the user has the `velocity.command.heap` permission, they will be able to generate a heap dump 48 | from the running Velocity instance, which will allow a detailed analysis of memory consumption. 49 | 50 | The generated heap dump will be found in the `dumps` folder. 51 | 52 | ## `/server` 53 | 54 | If the user has the `velocity.command.server` permission (by default, this is granted to all users), 55 | players can use this command to view and switch to another server. 56 | 57 | Executing just `/server` will send the user the name of the server they are currently on, along with 58 | options to move to other servers configured on the proxy. 59 | 60 | If a server name has been provided, Velocity will attempt to connect to the server. 61 | 62 | ## `/shutdown` 63 | 64 | :::note 65 | 66 | This command can only be executed from console. 67 | 68 | ::: 69 | 70 | When run, this will gracefully shut down the Velocity proxy. 71 | All players will be disconnected from the proxy, and plugins will have a chance to finish up before the proxy shuts down. 72 | An optional reason can be given, either as JSON or with [MiniMessage Format](https://docs.advntr.dev/minimessage/format.html). 73 | 74 | If the provided message starts with `"`, `[`, or `{`, then the message is attempted to be parsed as JSON. 75 | If this parsing fails, or the message starts with anything else, the message will be parsed as MiniMessage. 76 | 77 | 78 | ## `/glist` 79 | 80 | If the user has the `velocity.command.glist` permission (by default, this is granted to nobody), 81 | players can use this command to view the number of players currently on the proxy and use 82 | `/glist all` to get a listing of players per server. 83 | 84 | ## `/send` 85 | 86 | If the user has the `velocity.command.send` permission, they can send other players (or all 87 | players on the proxy) to another server. 88 | -------------------------------------------------------------------------------- /src/content/docs/velocity/admin/reference/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Reference 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Reference of Velocity's configuration options, system properties and other features. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/velocity/admin/reference/system-properties.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: System properties 3 | description: Documentation for the system properties and environment variables Velocity may check. 4 | slug: velocity/reference/system-properties 5 | --- 6 | 7 | These system properties and environment variables can be set when you start your server allowing for the configuration of various settings. 8 | 9 | :::danger[Danger Ahead] 10 | 11 | Setting flags for the JVM can alter how it operates and the same goes for the Velocity server. 12 | If you are unsure about what a flag does, it is recommended that you **do not use it**. 13 | 14 | ::: 15 | 16 | ## How they work 17 | 18 | System properties are set when you start your server. For example, if you are using a `.bat` or a `.sh` file to start your server, you can add the system properties to 19 | the file. For example: 20 | 21 | ```bash 22 | java -Dvelocity.packet-decode-logging=true -jar velocity.jar 23 | ``` 24 | 25 | :::note 26 | 27 | Some of Velocity's system properties contain a `.` character in their name. When using PowerShell, these will require wrapping in quotes. 28 | i.e. `"-Dvelocity.packet-decode-logging=true"` 29 | 30 | ::: 31 | 32 | Where a `-D` is used to set a system property, and the system property is `velocity.packet-decode-logging` with a value of `true`. 33 | Otherwise, just add them to the start command. 34 | 35 | :::note 36 | 37 | The default value shown may not be set for the property but will only be used by Velocity if it is not explicitly set. 38 | 39 | ::: 40 | 41 | ## List of system properties 42 | 43 | #### auth.forceSecureProfiles 44 | 45 | - **default**: `true` 46 | - **description**: Overrides `force-key-authentication` from the config. If not set, it will be automatically set to the current config value. 47 | 48 | #### velocity.natives-tmpdir 49 | 50 | - **default**: `unset` 51 | - **description**: Temporary directory for Velocity native files. (If set, it will also define `io.netty.native.workdir`) 52 | 53 | #### velocity.max-known-packs 54 | 55 | - **default**: `64` 56 | - **description**: Limits known packs to the Vanilla default to prevent crashing Velocity. 57 | 58 | #### velocity.max-packets-per-flush 59 | 60 | - **default**: `8192` 61 | - **description**: The max amount of packets before the queue is flushed automatically. 62 | 63 | #### velocity.log-server-backpressure 64 | 65 | - **default**: `false` 66 | - **description**: Whether Velocity should log if the server connection is writable and thus if the player connection will be auto-read. 67 | 68 | #### velocity.packet-decode-logging 69 | 70 | - **default**: `false` 71 | - **description**: Whether packet decoding errors should be logged extensively. 72 | 73 | #### velocity.increased-compression-cap 74 | 75 | - **default**: `false` 76 | - **description**: Whether the maximum uncompressed packet size should be set to its maximum supported limit (128 MiB) instead of the Vanilla limit (8 MiB). 77 | 78 | #### velocity.disable-native-transport 79 | 80 | - **default**: `false` 81 | - **description**: Whether to disable Netty's native transport methods like the io_uring support and Epoll. If set to true, Velocity will use Java's NIO transport instead. 82 | 83 | #### velocity.enable-iouring-transport 84 | 85 | - **default**: `false` 86 | - **description**: Enables Netty's io_uring transport when set to true. By default, Velocity only uses the Epoll (on Linux) and kqueue (on macOS) native transports. This property does not override the `velocity.disable-native-transport` property. 87 | 88 | #### velocity.natives-disabled 89 | 90 | - **default**: `false` 91 | - **description**: Whether native functionality for specific operating systems should be disabled. 92 | 93 | #### velocity.strictErrorHandling 94 | 95 | - **default**: `true` 96 | - **description**: Whether the client should disconnect on packet errors. Temporarily added in MC 1.20.5 and removed in 1.21.2 to help modded servers transition to this change. 97 | 98 | ## List of environment variables 99 | 100 | #### VELOCITY_FORWARDING_SECRET 101 | 102 | - **default**: `unset` 103 | - **description**: Overrides the forwarding secret inside the [`forwarding-secret-file`](/velocity/configuration#root-section). 104 | -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/api/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: API 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Guides for working with Velocity's API. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/api/scheduler.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using the scheduler 3 | description: A guide to the Scheduler API within Velocity allowing tasks to be run. 4 | slug: velocity/dev/scheduler-api 5 | --- 6 | 7 | The Velocity scheduler lets you decide when and how your plugin tasks run, allowing fine control 8 | over execution. On Velocity, there is no main thread. All tasks run using the Velocity scheduler are 9 | thus run asynchronously. 10 | 11 | ## Running a delayed task 12 | 13 | All scheduling works by using a [`TaskBuilder`](jd:velocity:com.velocitypowered.api.scheduler.Scheduler$TaskBuilder) 14 | returned from the [`Scheduler`](jd:velocity:com.velocitypowered.api.scheduler.Scheduler). 15 | This fluent builder may be chained to configure the details of the scheduling. 16 | 17 | ```java 18 | server.getScheduler() 19 | .buildTask(plugin, () -> { 20 | // do stuff here 21 | }) 22 | .delay(2L, TimeUnit.SECONDS) 23 | .schedule(); 24 | ``` 25 | 26 | Here, we are scheduling a task to run 2 seconds later. Velocity requires the instance of your 27 | plugin, `plugin` above. If you are scheduling a task from your main plugin class you may simply use 28 | `this`. 29 | 30 | Time arguments are specified as a `long` with a [`TimeUnit`](jd:java:java.util.concurrent.TimeUnit). 31 | Using time units makes scheduling delayed tasks more readable and allows for greater precision. 32 | `2L, TimeUnit.SECONDS` is far easier to understand than the ambiguous `2000L`. 33 | 34 | You can also use a [`Duration`](jd:java:java.time.Duration) to specify the time arguments, 35 | e.g.: `Duration.ofSeconds(5L)`. 36 | 37 | ## Running a repeating task 38 | 39 | Creating a repeating task is similar to a delayed task, but you must also specify 40 | [`repeat(long, TimeUnit)`](jd:velocity:com.velocitypowered.api.scheduler.Scheduler$TaskBuilder#repeat(long,java.util.concurrent.TimeUnit)). 41 | This example will repeat every 5 minutes. 42 | 43 | ```java 44 | server.getScheduler() 45 | .buildTask(plugin, () -> { 46 | // do stuff here 47 | }) 48 | .repeat(5L, TimeUnit.MINUTES) 49 | .schedule(); 50 | ``` 51 | 52 | ## Running a task now 53 | 54 | Tasks use the scheduler's cached thread pool for all execution, which reuses threads. To take 55 | advantage of this thread pool for running async tasks which run now, simply omit calling the _delay_ 56 | and _repeat_ methods of the `TaskBuilder`. 57 | 58 | ## Cancellation 59 | 60 | The [`schedule()`](jd:velocity:com.velocitypowered.api.scheduler.Scheduler$TaskBuilder#schedule()) 61 | method returns a [`ScheduledTask`](jd:velocity:com.velocitypowered.api.scheduler.ScheduledTask), 62 | which may then be used to cancel the task involved via the 63 | [`cancel()`](jd:velocity:com.velocitypowered.api.scheduler.ScheduledTask#cancel()) method. 64 | Tasks cannot be uncancelled. 65 | 66 | Additionally, [`task.status()`](jd:velocity:com.velocitypowered.api.scheduler.ScheduledTask#status()) 67 | returns the current status of the task. 68 | 69 | ```java 70 | ScheduledTask task = server.getScheduler() 71 | .buildTask(plugin, () -> { 72 | // do stuff here 73 | }) 74 | .repeat(5L, TimeUnit.MINUTES) 75 | .schedule(); 76 | // ... 77 | task.cancel(); 78 | // ... 79 | System.out.println(task.status()); 80 | ``` 81 | 82 | You can also schedule _self-cancelling_ tasks using a `Consumer`. 83 | 84 | ```java 85 | AtomicInteger integer = new AtomicInteger(0); 86 | 87 | ScheduledTask task = server.getScheduler() 88 | .buildTask(plugin, (selfTask) -> { 89 | // do stuff here, for example... 90 | if (integer.addAndGet(1) > 10) { 91 | selfTask.cancel(); 92 | } 93 | }) 94 | .repeat(Duration.ofSeconds(4L)) 95 | .schedule(); 96 | ``` 97 | 98 | ## Obtaining tasks from a plugin 99 | 100 | You can get all tasks scheduled by a plugin with 101 | [`tasksByPlugin(Object)`](jd:velocity:com.velocitypowered.api.scheduler.Scheduler#tasksByPlugin(java.lang.Object)). 102 | 103 | ```java 104 | Collection tasks = server.getScheduler().tasksByPlugin(plugin); 105 | // then you can control them, for example, cancel all task scheduled by a plugin 106 | for (ScheduledTask task : tasks) { 107 | task.cancel(); 108 | } 109 | ``` 110 | -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/getting-started/assets/installing-plugin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/velocity/dev/getting-started/assets/installing-plugin.png -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/getting-started/assets/new-project-velocity.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/velocity/dev/getting-started/assets/new-project-velocity.png -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/getting-started/assets/restart-ide.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/velocity/dev/getting-started/assets/restart-ide.png -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/getting-started/assets/velocity-plugin-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PaperMC/docs/4a0a11c5063baf059cfd5aa9fd34d3a83693e1d2/src/content/docs/velocity/dev/getting-started/assets/velocity-plugin-overview.png -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/getting-started/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting started 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Guides for getting started with developing a Velocity plugin. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/getting-started/pitfalls.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Common pitfalls 3 | description: How to avoid common pitfalls within Velocity. 4 | slug: velocity/dev/pitfalls 5 | --- 6 | 7 | While we try to make the API a pleasure to use, there are the occasional rough edges, and you should 8 | be aware of them. 9 | 10 | ## Accessing the API at construction time 11 | 12 | In Velocity, plugin loading is split into two steps: construction and initialization. The code in 13 | your plugin's constructor is part of the construction phase. There is very little you can do safely 14 | during construction, especially as the API does not specify which operations are safe to run during 15 | construction. Notably, you can't register an event listener in your constructor, because you need to 16 | have a valid plugin registration, but Velocity can't register the plugin until the plugin has been 17 | constructed. 18 | 19 | To break this cycle, you should always wait for initialization, which is indicated when Velocity 20 | fires the [`ProxyInitializeEvent`](jd:velocity:com.velocitypowered.api.event.proxy.ProxyInitializeEvent). 21 | We can do things on initialization by adding a listener for this event, as shown below. 22 | Note that Velocity automatically registers your plugin main class as a listener. 23 | 24 | ```java 25 | @Subscribe 26 | public void onProxyInitialization(ProxyInitializeEvent event) { 27 | // Do some operation demanding access to the Velocity API here. 28 | // For instance, we could register an event: 29 | server.getEventManager().register(this, new PluginListener()); 30 | } 31 | ``` 32 | 33 | ## Audience operations are not fully supported 34 | 35 | Velocity currently does not support all Audience operations of the Adventure API, so these operations should be handled on the backend. 36 | Furthermore, playing sound was previously considered infeasible, as for versions below 1.19.3, a registry of hardcoded sound IDs is required. 37 | 38 | | Operation | Supported | 39 | | -------------------------- | ----------| 40 | | Chat messages | Yes | 41 | | Action bar messages | Yes | 42 | | Titles | Yes | 43 | | Bossbars | Yes | 44 | | Tablist header and footer | Yes | 45 | | Resource packs | Yes | 46 | | Sound | No | 47 | | Book | No | 48 | -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/how-to/dependencies.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Dependency management 3 | description: How to handle dependencies within your Velocity plugin. 4 | slug: velocity/dev/dependency-management 5 | --- 6 | 7 | Dependencies are common. You need to hook into another plugin. You don't want to write the same code 8 | someone else has already solved. Whatever you do, you need a way to manage your dependencies 9 | effectively. 10 | 11 | ## Plugin dependencies 12 | 13 | Adding a dependency on another plugin is done with the 14 | [`@Plugin`](jd:velocity:com.velocitypowered.api.plugin.Plugin) 15 | annotation in your main class. Let's revisit that briefly: 16 | 17 | ```java 18 | @Plugin( 19 | id = "myfirstplugin", 20 | name = "My Plugin", 21 | version = "0.1.0" 22 | ) 23 | public class VelocityTest { 24 | // ... 25 | } 26 | ``` 27 | 28 | Say we have a dependency on another plugin, call it `wonderplugin`. To add it as a dependency, do 29 | the following: 30 | 31 | ```java 32 | @Plugin( 33 | id = "myfirstplugin", 34 | name = "My Plugin", 35 | version = "0.1.0", 36 | dependencies = { 37 | @Dependency(id = "wonderplugin") 38 | } 39 | ) 40 | public class VelocityTest { 41 | // ... 42 | } 43 | ``` 44 | 45 | The id of the dependency is the same as the other plugin's `id` from its `@Plugin` annotation. This 46 | is why having a stable plugin ID is important. 47 | 48 | That's it! Now, your plugin will require `wonderplugin` to load, and when it does, it will load 49 | _after_ `wonderplugin`. 50 | 51 | To specify multiple dependencies, separate them by commas: 52 | `dependencies = {@Dependency(id = "wonderplugin"), @Dependency(id = "otherplugin")}` 53 | 54 | ## Optional plugin dependencies 55 | 56 | To make a dependency optional, add `optional = true`, like shown: 57 | 58 | ```java 59 | @Plugin( 60 | id = "myfirstplugin", 61 | name = "My Plugin", 62 | version = "0.1.0", 63 | dependencies = { 64 | @Dependency(id = "wonderplugin", optional = true) 65 | } 66 | ) 67 | public class VelocityTest { 68 | // ... 69 | } 70 | ``` 71 | 72 | ## External dependencies 73 | 74 | :::caution 75 | 76 | Please remember to relocate any dependencies you shade. Failure to relocate will lead to dependency 77 | conflicts with other plugins. 78 | 79 | ::: 80 | 81 | Dependencies on other libraries aren't handled by Velocity. You will need to add them using your 82 | build system. 83 | 84 | If your plugin does not shade its dependencies, but rather attaches them from a directory, you may 85 | use the [`PluginManager`](jd:velocity:com.velocitypowered.api.plugin.PluginManager)'s 86 | [`addToClasspath`](jd:velocity:com.velocitypowered.api.plugin.PluginManager#addToClasspath(java.lang.Object,java.nio.file.Path)) 87 | method instead of using reflection to access the 88 | [`ClassLoader`](jd:java:java.lang.ClassLoader). 89 | -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/how-to/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: How-to guides 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | How-to guides for developing your Velocity plugin. 9 | 10 | 11 | -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/how-to/porting-from-velocity-1.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Porting your plugin from Velocity 1.x.x 3 | description: How to port your plugin from Velocity 1.x.x to modern API. 4 | slug: velocity/dev/porting-plugins-from-velocity-1 5 | --- 6 | 7 | Velocity 3.0.0 includes important API changes from the Velocity 1.x.x series. **Please read this 8 | document very carefully**. 9 | 10 | ## Minimum supported Java version bump 11 | 12 | Velocity 3.3.x and above now requires Java 17 and above. 13 | 14 | ## Removal of legacy dependencies 15 | 16 | We removed all support for the old `text` 3 library. For `text` 3.x.x (and all the APIs that depend 17 | on it), direct equivalents are available in [Adventure](https://docs.advntr.dev/), which was 18 | introduced in Velocity 1.1.0. 19 | 20 | `toml4j`, deprecated in Velocity 1.1.0 (as it is no longer maintained), has not been removed to 21 | provide more time for plugins to migrate to Configurate. However, you should prepare to either 22 | switch to Configurate or shade `toml4j` into your plugin directly. 23 | 24 | ## New asynchronous event system 25 | 26 | Velocity 3.0.0 contains a backport of Velocity Polymer's event system, which differs from Velocity 27 | 1.x.x's event system in a number of ways. Velocity 1.x.x's event model forced all events to be 28 | executed asynchronously on a fixed-size thread pool, which has proven over time to be a flawed 29 | model. 30 | 31 | Existing event handlers will continue to work unmodified on Velocity 3.0.0, as all event handlers 32 | are assumed to be asynchronous blocking handlers by default. However, there are some new APIs 33 | introduced for handling continuations - see the [event API page](/velocity/dev/event-api) for more 34 | information. However, you are encouraged to migrate your event listeners to the new event API 35 | paradigms. 36 | -------------------------------------------------------------------------------- /src/content/docs/velocity/dev/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Development 3 | tableOfContents: false 4 | --- 5 | 6 | import PageCards from "/src/components/PageCards.astro"; 7 | 8 | Welcome to the Velocity development guide! This guide includes information and tutorials for 9 | developers to create and expand on Velocity plugins. 10 | 11 | #### Getting started 12 | 13 | 14 | 15 | #### How-to guides 16 | 17 | 18 | 19 | #### API 20 | 21 | 22 | -------------------------------------------------------------------------------- /src/content/docs/velocity/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Velocity Documentation 3 | --- 4 | 5 | import { CardGrid, LinkCard } from "@astrojs/starlight/components"; 6 | 7 | Velocity is the ridiculously scalable, flexible Minecraft proxy. 8 | 9 | ## Getting started 10 | 11 | It is simple to get started with Velocity. Get started with our 12 | [Getting Started guide](/velocity/getting-started). 13 | 14 | ## I need help 15 | 16 | If you need some help with Velocity, please seek help in the following places: 17 | 18 | ### 📖 These Docs 19 | 20 | We have put a lot of effort into documenting Velocity as much as possible with our new website and 21 | our coverage will continue to expand. We strongly encourage you to check the sidebar of the docs for 22 | relevant resources. Helping yourself using the resources in these docs saves all of us time. 23 | 24 | We recommend you visit the [frequently asked questions](/velocity/faq) to begin your 25 | search. Most common issues with Velocity are answered there. 26 | 27 | Please do not be offended if we respond to your question linking back here. Asking us a question 28 | already answered in the documentation doesn't help anyone. 29 | 30 | ### 💬 Our Discord 31 | 32 | If you have searched the docs and didn't find the answer to your question, then it is time to 33 | [join our Discord](https://discord.gg/papermc) to ask your question. 34 | 35 | 36 | 41 | 46 | 47 | -------------------------------------------------------------------------------- /src/content/docs/waterfall/configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Configuration 3 | description: Configuration guide for Waterfall. 4 | slug: waterfall/configuration 5 | banner: 6 | destructive: true 7 | content: We recommend you transition to Velocity. For more information, see the announcement. 8 | --- 9 | 10 | import ConfigNode from "/src/components/ConfigNode.astro"; 11 | import WaterfallConfigYML from "/src/config/waterfall/waterfall-config.yml?raw"; 12 | import { parse } from "yaml"; 13 | 14 | This page details the various configuration settings exposed by Waterfall. These settings can be 15 | found in waterfall.yml. 16 | 17 | If you want information on settings in BungeeCord's config.yml, you should see its respective 18 | documentation pages. 19 | 20 | :::note 21 | 22 | The below YAML shows you the structure and default values for the global configuration. 23 | 24 | Click on a leaf node to view the description for that setting. 25 | 26 | ::: 27 | 28 | 29 | -------------------------------------------------------------------------------- /src/content/docs/waterfall/getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting started 3 | description: How to get started with running Waterfall. 4 | slug: waterfall/getting-started 5 | banner: 6 | destructive: true 7 | content: We recommend you transition to Velocity. For more information, see the announcement. 8 | --- 9 | 10 | ## What is Waterfall? 11 | 12 | Waterfall is a fork of BungeeCord, a proxy used primarily to teleport players between multiple 13 | Minecraft servers. 14 | 15 | Waterfall focuses on three main areas: 16 | 17 | - Stability: Waterfall aims to be stable. We will achieve this through making the code base testable 18 | and discouraging practices that lead to proxy lag. 19 | - Features: Waterfall aims to include more features than canonical BungeeCord. 20 | - Scalability: Waterfall should be able to handle a large number of concurrent players, given a 21 | reasonably modern CPU, memory, and good network connection. 22 | 23 | ## Requirements 24 | 25 | Waterfall requires **Java 8** or newer to run. The Paper team recommends you run on Java 11 or 26 | higher. Generally, LTS versions of Java are targeted, though you may have luck on newer versions. 27 | 28 | ## Migrating from BungeeCord 29 | 30 | Waterfall is a drop in replacements for BungeeCord, you don't need to make any changes to your 31 | configuration. 32 | 33 | ## Getting a proxy JAR 34 | 35 | Paper provides runnable proxy JARs directly from our [downloads page](https://papermc.io/downloads/waterfall). 36 | 37 | Click on the build number to download a file. 38 | 39 | ## Running the proxy 40 | 41 | To run the proxy, simply start it up like any other Java application. 42 | 43 | Open your terminal, navigate to the saved location, and then run 44 | 45 | ```bash 46 | java -Xms512M -Xmx512M -jar waterfall-###.jar 47 | ``` 48 | 49 | Aikar's recommended flags for Waterfall are as follows: 50 | 51 | ```bash 52 | java -Xms512M -Xmx512M -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -jar waterfall-###.jar 53 | ``` 54 | 55 | The amount of memory can be set by changing the numbers in the `-Xms` and `-Xmx` flags. 56 | 57 | To configure your proxy, see the [configuration](/waterfall/configuration) page. 58 | 59 | ## Updating the proxy 60 | 61 | To update the proxy, first stop it safely by executing the `end` command. Then replace the old proxy 62 | JAR with a new one, and start the proxy. That's it. 63 | -------------------------------------------------------------------------------- /src/content/docs/waterfall/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Waterfall Documentation 3 | tableOfContents: false 4 | banner: 5 | destructive: true 6 | content: We recommend you transition to Velocity. For more information, see the announcement. 7 | --- 8 | 9 | import PageCards from "/src/components/PageCards.astro"; 10 | 11 | Waterfall is the BungeeCord fork that aims to improve performance and stability. 12 | 13 | 14 | -------------------------------------------------------------------------------- /src/env.d.ts: -------------------------------------------------------------------------------- 1 | import type { AstroMarkdownOptions } from "@astrojs/markdown-remark"; 2 | 3 | declare global { 4 | // for passing the Markdown configuration to the on-demand renderer 5 | var markdownConfig: AstroMarkdownOptions; 6 | } 7 | -------------------------------------------------------------------------------- /src/pages/robots.txt.ts: -------------------------------------------------------------------------------- 1 | import type { APIRoute } from "astro"; 2 | 3 | const getRobotsTxt = (sitemapURL?: URL) => { 4 | let content = `User-agent: *\nAllow: /\n`; 5 | if (sitemapURL) { 6 | content += `\nSitemap: ${sitemapURL.href}\n`; 7 | } 8 | 9 | return content; 10 | }; 11 | 12 | export const GET: APIRoute = ({ site }) => { 13 | const sitemapURL = site ? new URL("sitemap-index.xml", site) : undefined; 14 | return new Response(getRobotsTxt(sitemapURL)); 15 | }; 16 | -------------------------------------------------------------------------------- /src/styles/custom.css: -------------------------------------------------------------------------------- 1 | /* poppins-latin-500-normal - defined as 600, because actual 600 is too bold */ 2 | @font-face { 3 | font-family: "Poppins"; 4 | font-style: normal; 5 | font-display: swap; 6 | font-weight: 600; 7 | src: 8 | url(@fontsource/poppins/files/poppins-latin-500-normal.woff2) format("woff2"), 9 | url(@fontsource/poppins/files/poppins-latin-500-normal.woff) format("woff"); 10 | unicode-range: 11 | U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, 12 | U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; 13 | } 14 | 15 | :root { 16 | --sl-font: Poppins; 17 | --sl-font-mono: "JetBrains Mono"; 18 | } 19 | 20 | /* make images in markup wide and centered */ 21 | .sl-markdown-content img { 22 | margin: 0 auto; 23 | } 24 | .sl-markdown-content img:not([alt="Diagram"]) { 25 | width: 100%; 26 | } 27 | .sl-markdown-content .img-inline img { 28 | margin: 0; 29 | width: auto; 30 | } 31 | .sl-markdown-content .img-inline-center img { 32 | width: auto; 33 | } 34 | 35 | /* use custom font first instead of system */ 36 | .sl-badge { 37 | font-family: var(--__sl-font-mono); 38 | } 39 | 40 | /* Safari fixes for logo sizing */ 41 | .hero-html > img { 42 | object-fit: contain; 43 | width: min(70%, 20rem); 44 | height: auto; 45 | margin-inline: auto; 46 | } 47 | 48 | /* make index page hero smaller vertically */ 49 | @media (min-width: 50rem) { 50 | .hero { 51 | padding-block: clamp(2.5rem, calc(1rem + 2.5vmin), 10rem); 52 | } 53 | } 54 | 55 | /* fix too large TOC on large screens */ 56 | @media (min-width: 96rem) { 57 | :root { 58 | --sl-content-width: 64rem; 59 | } 60 | } 61 | 62 | /* Dark mode colors. */ 63 | :root { 64 | /* raw values for setting opacity */ 65 | --sl-color-accent-raw: 37, 99, 235; 66 | 67 | --sl-color-accent-low: #1e3a8a; 68 | --sl-color-accent: rgb(var(--sl-color-accent-raw)); 69 | --sl-color-accent-high: #60a5fa; 70 | --sl-color-white: #ffffff; 71 | --sl-color-gray-1: #e2e5e9; 72 | --sl-color-gray-2: #d1d5db; 73 | --sl-color-gray-3: #9fa5af; 74 | --sl-color-gray-4: #3f4347; 75 | --sl-color-gray-5: #2a2c2e; 76 | --sl-color-gray-6: #181a1b; 77 | --sl-color-black: #111111; 78 | 79 | /* caution asides - bump saturation and lightness +5% */ 80 | --sl-color-orange-low: hsl(var(--sl-hue-orange), 44%, 27%); 81 | } 82 | 83 | /* Light mode colors. */ 84 | :root[data-theme="light"] { 85 | /* raw values for setting opacity */ 86 | --sl-color-accent-raw: 37, 99, 235; 87 | 88 | --sl-color-accent-low: #60a5fa; 89 | --sl-color-accent: rgb(var(--sl-color-accent-raw)); 90 | --sl-color-accent-high: #1e3a8a; 91 | --sl-color-white: #111111; 92 | --sl-color-gray-1: #181a1b; 93 | --sl-color-gray-2: #2a2c2e; 94 | --sl-color-gray-3: #3f4347; 95 | --sl-color-gray-4: #9fa5af; 96 | --sl-color-gray-5: #d1d5db; 97 | --sl-color-gray-6: #e2e5e9; 98 | --sl-color-gray-7: #f3f4f6; 99 | --sl-color-black: #ffffff; 100 | 101 | /* return to Starlight default */ 102 | --sl-color-orange-low: hsl(var(--sl-hue-orange), 90%, 88%); 103 | } 104 | -------------------------------------------------------------------------------- /src/utils/config.ts: -------------------------------------------------------------------------------- 1 | export interface LeafData { 2 | description: string; 3 | default?: string; 4 | } 5 | 6 | export interface MessageData { 7 | message: string; 8 | color?: string; 9 | inline?: boolean; 10 | } 11 | 12 | export type Data = { [key: string]: Data } | LeafData | MessageData; 13 | 14 | interface VanillaLeafData extends LeafData { 15 | vanilla?: string; 16 | } 17 | 18 | type VanillaData = { [key: string]: Data } | VanillaLeafData | MessageData; 19 | 20 | // replaces "default" values with "vanilla" values, removes them if no "vanilla" value is defined 21 | export const filterVanilla = (input: VanillaData): Data | null => { 22 | if ("message" in input) { 23 | return input; // MessageData 24 | } 25 | 26 | if ("description" in input) { 27 | const leaf = input as LeafData; 28 | if ("vanilla" in leaf) { 29 | leaf.default = (leaf as VanillaLeafData).vanilla!; 30 | return leaf; 31 | } 32 | 33 | return null; // remove key 34 | } 35 | 36 | const result: { [key: string]: Data } = {}; 37 | for (const key in input) { 38 | const converted = filterVanilla(input[key]); 39 | if (converted !== null) { 40 | result[key] = converted; 41 | } 42 | } 43 | 44 | return Object.keys(result).length > 0 ? result : null; 45 | }; 46 | -------------------------------------------------------------------------------- /src/utils/git.ts: -------------------------------------------------------------------------------- 1 | import { execSync } from "child_process"; 2 | 3 | export interface CommitterInfo { 4 | name: string; 5 | href: string; 6 | } 7 | 8 | export interface CommitInfo { 9 | hash: string; 10 | committer: CommitterInfo; 11 | } 12 | 13 | export const GITHUB_OPTIONS: RequestInit = process.env.GITHUB_TOKEN 14 | ? { 15 | headers: { 16 | Accept: "application/vnd.github+json", 17 | "User-Agent": "PaperMC/docs (https://docs.papermc.io)", 18 | Authorization: `Bearer ${process.env.GITHUB_TOKEN}`, 19 | }, 20 | } 21 | : { 22 | headers: { 23 | Accept: "application/vnd.github+json", 24 | "User-Agent": "PaperMC/docs (https://docs.papermc.io)", 25 | }, 26 | }; 27 | 28 | export const REPO = "PaperMC/docs"; 29 | const cache = new Map(); 30 | 31 | export const getCommitInfo = async (filePath: string): Promise => { 32 | let hash: string, email: string, name: string; 33 | try { 34 | [hash, email, name] = execSync(`git log -1 --format="%H,%ae,%an" -- "${filePath}"`).toString().trim().split(",", 3); 35 | } catch (e) { 36 | return null; 37 | } 38 | 39 | const cached = cache.get(email); 40 | if (cached) { 41 | return { hash, committer: cached }; 42 | } 43 | 44 | const info: CommitterInfo = { name, href: `mailto:${email}` }; 45 | 46 | const res = await fetch(`https://api.github.com/repos/${REPO}/commits/${hash}`, GITHUB_OPTIONS); 47 | if (res.ok) { 48 | const commit = await res.json(); 49 | info.href = commit.author.html_url; 50 | } 51 | 52 | cache.set(email, info); 53 | return { hash, committer: info }; 54 | }; 55 | -------------------------------------------------------------------------------- /src/utils/markdown.ts: -------------------------------------------------------------------------------- 1 | import { createMarkdownProcessor } from "@astrojs/markdown-remark"; 2 | 3 | const renderer = await createMarkdownProcessor(globalThis.markdownConfig); 4 | 5 | export const render = async (content: string): Promise => { 6 | const code = (await renderer.render(content)).code; 7 | 8 | return code.startsWith("

") && code.endsWith("

") ? code.substring(3, code.length - 4) : code; 9 | }; 10 | -------------------------------------------------------------------------------- /src/utils/remark/code_const.ts: -------------------------------------------------------------------------------- 1 | import type { RemarkPlugin } from "@astrojs/markdown-remark"; 2 | import type { Literal } from "mdast"; 3 | import { visit } from "unist-util-visit"; 4 | 5 | // replaces constants in code blocks 6 | // expression format: \{CONSTANT_NAME} 7 | 8 | interface Options { 9 | constants: Record; 10 | } 11 | 12 | const plugin: RemarkPlugin = ({ constants }: Options) => { 13 | return (tree) => { 14 | visit(tree, ["code", "inlineCode"], (node) => { 15 | if (node.type === "code" && !node.meta?.includes("replace")) { 16 | return; 17 | } 18 | 19 | const code = node as Literal; 20 | code.value = code.value.replace(/\\\{([^}]+?)}/g, (_, name) => constants[name] ?? name); 21 | }); 22 | }; 23 | }; 24 | 25 | export default plugin; 26 | -------------------------------------------------------------------------------- /src/utils/remark/javadoc.ts: -------------------------------------------------------------------------------- 1 | import type { RemarkPlugin } from "@astrojs/markdown-remark"; 2 | import { deadOrAlive } from "dead-or-alive"; 3 | import { visit } from "unist-util-visit"; 4 | 5 | // replaces special Markdown links with Javadoc URLs 6 | // link format: jd:[:][:] 7 | 8 | interface Target { 9 | url: string; 10 | module?: string; // default 11 | } 12 | 13 | interface Options { 14 | targets: Record; 15 | } 16 | 17 | const asUrl = (name: string): string => { 18 | let [name0, hash] = name.split("#", 2); 19 | name0 = name0.replaceAll(".", "/").replaceAll("$", "."); 20 | 21 | return `${name0}.html` + (hash ? `#${hash}` : ""); 22 | }; 23 | 24 | const parse = async (url: string, { targets }: Options): Promise => { 25 | const match = /^jd:(.+?)(?::(.+?))?(?::(.+?))?$/.exec(url); 26 | if (!match) { 27 | return null; 28 | } 29 | 30 | const target = targets[match[1]]; 31 | if (!target) { 32 | return null; 33 | } 34 | 35 | const targetUrl = typeof target !== "string" ? target.url : target; 36 | 37 | const name = match[3] ?? match[2]; 38 | if (!name) { 39 | return targetUrl; 40 | } 41 | 42 | const module = match[3] ? match[2] : typeof target !== "string" ? target.module : undefined; 43 | 44 | const parsed: string = `${targetUrl}/${module ? `${module}/` : ""}${asUrl(name)}`; 45 | 46 | const result = await deadOrAlive(parsed, { 47 | findUrls: false, 48 | followMetaHttpEquiv: false, 49 | userAgent: "PaperMC/docs (https://docs.papermc.io)", 50 | }); 51 | if (result.status !== "alive") { 52 | const error = new Error(`Javadoc link "${url}" is not valid`); 53 | if (process.env.NODE_ENV === "production") { 54 | console.error(error); 55 | 56 | // throwing an error does not exit the build process, it silently fails 57 | // we don't want missing pages, so exit the process instead 58 | process.exit(1); 59 | } else { 60 | throw error; 61 | } 62 | } 63 | 64 | return parsed; 65 | }; 66 | 67 | const plugin: RemarkPlugin = (options: Options) => { 68 | return async (tree) => { 69 | const promises: Promise[] = []; 70 | visit(tree, "link", (node) => { 71 | promises.push( 72 | parse(node.url, options).then((url) => { 73 | node.url = url ?? node.url; 74 | }) 75 | ); 76 | }); 77 | await Promise.all(promises); 78 | }; 79 | }; 80 | 81 | export default plugin; 82 | -------------------------------------------------------------------------------- /src/utils/sidebar.ts: -------------------------------------------------------------------------------- 1 | export interface SidebarLink { 2 | type: "link"; 3 | label: string; 4 | href: string; 5 | } 6 | 7 | export interface SidebarGroup { 8 | type: "group"; 9 | label: string; 10 | entries: (SidebarLink | SidebarGroup)[]; 11 | } 12 | 13 | export type SidebarEntry = SidebarLink | SidebarGroup; 14 | 15 | export const flattenEntries = (entries: SidebarEntry[], result: SidebarEntry[] = []): SidebarEntry[] => { 16 | for (const entry of entries) { 17 | result.push(entry); 18 | if (entry.type === "group") { 19 | flattenEntries(entry.entries, result); 20 | } 21 | } 22 | 23 | return result; 24 | }; 25 | -------------------------------------------------------------------------------- /src/utils/versions.ts: -------------------------------------------------------------------------------- 1 | import { GITHUB_OPTIONS } from "./git"; 2 | 3 | // this is resolved on build-time, not by the client 4 | 5 | interface Latest { 6 | release: string; 7 | snapshot: string; 8 | } 9 | 10 | interface Version { 11 | id: string; 12 | type: "release" | "snapshot" | "old_beta" | "old_alpha"; 13 | } 14 | 15 | interface Manifest { 16 | latest: Latest; 17 | versions: Version[]; 18 | } 19 | 20 | // prettier-ignore 21 | const manifest: Manifest = await fetch("https://piston-meta.mojang.com/mc/game/version_manifest_v2.json") 22 | .then((r) => r.json()); 23 | 24 | export const LATEST_MC_RELEASE = manifest.latest.release; 25 | 26 | interface Project { 27 | project_id: string; 28 | project_name: string; 29 | version_groups: string[]; 30 | versions: string[]; 31 | } 32 | 33 | const paperProject: Project = await fetch("https://api.papermc.io/v2/projects/paper").then((r) => r.json()); 34 | 35 | export const LATEST_PAPER_RELEASE = paperProject.versions[paperProject.versions.length - 1]; 36 | 37 | const velocityProject: Project = await fetch("https://api.papermc.io/v2/projects/velocity").then((r) => r.json()); 38 | 39 | export const LATEST_VELOCITY_RELEASE = velocityProject.versions[velocityProject.versions.length - 1]; 40 | 41 | const foliaProject: Project = await fetch("https://api.papermc.io/v2/projects/folia").then((r) => r.json()); 42 | 43 | export const LATEST_FOLIA_RELEASE = foliaProject.versions[foliaProject.versions.length - 1]; 44 | 45 | const waterfallProject: Project = await fetch("https://api.papermc.io/v2/projects/waterfall").then((r) => r.json()); 46 | 47 | export const LATEST_WATERFALL_RELEASE = waterfallProject.versions[waterfallProject.versions.length - 1]; 48 | 49 | interface Tag { 50 | name: string; 51 | } 52 | 53 | const userdevVersions: string[] = await fetch("https://api.github.com/repos/PaperMC/paperweight/tags", GITHUB_OPTIONS) 54 | .then((r) => (r.ok ? r.json() : [{ name: "v0.0.0" }])) 55 | .then((tags: Tag[]) => tags.map((t) => t.name.substring(1))); 56 | 57 | export const LATEST_USERDEV_RELEASE = userdevVersions[0]; 58 | 59 | export const LATEST_RELEASES: Record = { 60 | paper: LATEST_PAPER_RELEASE, 61 | velocity: LATEST_VELOCITY_RELEASE, 62 | folia: LATEST_FOLIA_RELEASE, 63 | waterfall: LATEST_WATERFALL_RELEASE, 64 | userdev: LATEST_USERDEV_RELEASE, 65 | }; 66 | -------------------------------------------------------------------------------- /svelte.config.ts: -------------------------------------------------------------------------------- 1 | import { vitePreprocess } from "@astrojs/svelte"; 2 | 3 | export default { 4 | preprocess: vitePreprocess(), 5 | }; 6 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "astro/tsconfigs/strict", 3 | "include": [".astro/types.d.ts", "**/*"], 4 | "exclude": ["dist"] 5 | } 6 | --------------------------------------------------------------------------------