No API records

Co-authored-by: Doc <git@mrdoc.dev>

.editorconfig

@@ -18,7 +18,7 @@ indent_style = tab
 [*.bat]
 end_of_line = crlf
 
-[*.yml]
+[{*.yaml,*.yml}]
 indent_size = 2
 
 [{*.patch,*.md}]

.github/CODEOWNERS

@@ -1,2 +1,13 @@
-* @PaperMC/paper-maintainers
-/.github/CODEOWNERS @PaperMC/core-team
+# default ownership
+* @papermc/paper-maintainers
+
+# tooling
+/.github/workflows/ @papermc/tooling
+/gradle/ @papermc/tooling
+/paper-api/build.gradle.kts @papermc/tooling
+/paper-server/build.gradle.kts @papermc/tooling
+/build.gradle.kts @papermc/tooling
+/gradle.properties @papermc/tooling
+/settings.gradle.kts @papermc/tooling
+
+/.github/CODEOWNERS @papermc/leadership-team

.github/workflows/build.yaml

@@ -5,14 +5,17 @@
 # of the PR relating to this action.
 
 name: Build Paper
+
 on:
-  push:
   pull_request:
     types:
       - opened
       - reopened
       - synchronize
       - labeled
+  push:
+    branches-ignore:
+      - main
 
 jobs:
   build:
@@ -107,7 +110,7 @@ jobs:
         if: always()
         uses: actions/upload-artifact@v7
         with:
-          name: Test Results
+          name: test-results
           path: |
             **/build/test-results/test/TEST-*.xml
 
@@ -137,12 +140,12 @@ jobs:
           publishing-task: ":paper-api:publishAllPublicationsTo_githubPackages_PRsRepository publishDevBundlePublicationTo_githubPackages_PRsRepository -PpublishDevBundle"
   event_file:
     name: "Event File"
-    # Only run on PRs if the source branch is on someone else's repo
-    if: ${{ github.event_name != 'pull_request' || github.repository != github.event.pull_request.head.repo.full_name }}
+    needs: build
+    if: ${{ !cancelled() && needs.build.result != 'skipped' }}
     runs-on: ubuntu-latest
     steps:
       - name: Upload
         uses: actions/upload-artifact@v7
         with:
-          name: Event File
+          name: event-data
           path: ${{ github.event_path }}

.github/workflows/close_invalid_prs.yml

@@ -2,7 +2,11 @@ name: Close invalid PRs
 
 on:
   pull_request_target:
-    types: [ opened ]
+    types:
+      - opened
+
+permissions:
+  pull-requests: write
 
 jobs:
   run:
@@ -12,7 +16,7 @@ jobs:
         github.head_ref == 'main' ||
         github.event.pull_request.head.repo.owner.type != 'User'
       )
-    runs-on: ubuntu-latest
+    runs-on: namespace-profile-linux-small
     steps:
       - uses: superbrothers/close-pull-request@v3
         id: "main_branch"

.github/workflows/issues-label-version.yaml

@@ -0,0 +1,185 @@
+on:
+  issues:
+    types:
+      - opened
+
+jobs:
+  detect-version:
+    runs-on: namespace-profile-linux-small
+    timeout-minutes: 5
+    permissions:
+      issues: read
+    outputs:
+      version: ${{ steps.detect.outputs.version }}
+    steps:
+      - id: detect
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            // Capturing Groups:
+            // 1 = Brand
+            // 2 = Minecraft Version
+            // 3 = Build Number
+            // 4 = Git Branch/Commit
+            // 5 = Build Time
+            const NEW_PATTERN = /This server is running ([A-Za-z0-9]+) version ([\d\.]+)-(DEV|\d+)-(.*) \((.*)\) \(Implementing API version .*\)(?: \(Git: .*\))?/;
+
+            // Capturing Groups:
+            // 1 = Brand
+            // 2 = Minecraft Version
+            const OLD_PATTERN = /This server is running ([A-Za-z0-9]+) version .* \(MC: ([^\)]+)\) \(Implementing API version .*\)(?: \(Git: .*\))?/;
+
+            if (!context.payload.issue.body) {
+              core.info("Issue body is empty; unable to detect version.");
+              return;
+            }
+
+            let version;
+
+            const match = context.payload.issue.body.match(NEW_PATTERN);
+            if (match && match.length === 6) {
+              version = match[2];
+            } else {
+              const oldMatch = context.payload.issue.body.match(OLD_PATTERN);
+              if (oldMatch) {
+                version = oldMatch[2];
+              }
+            }
+
+            if (!version) {
+              core.info("Unable to determine the Minecraft version from the issue body.");
+              return;
+            }
+
+            core.info(`Detected Minecraft version: ${version}`);
+            core.setOutput('version', version);
+
+  label-version:
+    needs: detect-version
+    if: needs.detect-version.outputs.version != ''
+    runs-on: namespace-profile-linux-small
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const version = '${{ needs.detect-version.outputs.version }}';
+
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.issue.number,
+              labels: [`version: ${version}`],
+            });
+
+            core.info(`Added version label for ${version}.`);
+
+  check-support:
+    needs:
+      - detect-version
+      - label-version
+    if: needs.detect-version.outputs.version != ''
+    runs-on: namespace-profile-linux-small
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const version = '${{ needs.detect-version.outputs.version }}';
+
+            const apiUrl = `https://fill.papermc.io/v3/projects/paper/versions/${encodeURIComponent(version)}`;
+            core.info(`Fetching version information from ${apiUrl}`);
+
+            let supportStatus;
+            let supportEnd;
+
+            try {
+              const response = await fetch(apiUrl, {
+                headers: {
+                  'Accept': 'application/json',
+                  'User-Agent': `GitHub Actions (${context.repo.owner}/${context.repo.repo})`,
+                },
+              });
+
+              if (response.status === 404) {
+                core.info(`Fill has no information for version ${version}.`);
+                return;
+              }
+
+              if (!response.ok) {
+                core.error(`Fill returned HTTP ${response.status}: ${response.statusText}`);
+                return;
+              }
+
+              const data = await response.json();
+              supportStatus = data?.version?.support?.status;
+              supportEnd = data?.version?.support?.end;
+            } catch (error) {
+              core.warning(`Failed to fetch support information: ${error}`);
+              return;
+            }
+
+            core.info(`Fill support status for ${version}: ${supportStatus}`);
+
+            // Only comment for deprecated or unsupported versions.
+            let comment;
+
+            if (supportStatus === 'UNSUPPORTED') {
+              comment =
+                `⚠️ **Minecraft ${version} is unsupported.**\n\n` +
+                `This version is no longer supported by PaperMC. ` +
+                (supportEnd
+                  ? `Support _ended_ on ${supportEnd}. `
+                  : '') +
+                `Please consider upgrading to a supported Minecraft version.`;
+            } else if (supportStatus === 'DEPRECATED') {
+              comment =
+                `⚠️ **Minecraft ${version} is deprecated.**\n\n` +
+                `This version is deprecated by PaperMC. ` +
+                (supportEnd
+                  ? `Support will end on ${supportEnd}. `
+                  : '') +
+                `Please consider upgrading to a supported Minecraft version.`;
+            } else {
+              core.info(`${version} is supported or has an unknown status.`);
+              return;
+            }
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.issue.number,
+              body: comment,
+            });
+
+            if (supportStatus === 'UNSUPPORTED') {
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.payload.issue.number,
+                  name: 'status: needs triage',
+                });
+              } catch (error) {
+                // ignore - missing label is not an error
+              }
+
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.payload.issue.number,
+                labels: ['resolution: unsupported'],
+              });
+
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.payload.issue.number,
+                state: 'closed',
+                state_reason: 'not_planned',
+              });
+            }

.github/workflows/pr_review_signal.yml

@@ -9,6 +9,6 @@ permissions: {}
 
 jobs:
   signal:
-    runs-on: ubuntu-latest
+    runs-on: namespace-profile-linux-small
     steps:
       - run: echo "A PR review was submitted"

.github/workflows/pr_review_status.yml

@@ -22,7 +22,7 @@ jobs:
     concurrency:
       group: pr-review-status-${{ github.event.workflow_run.head_sha }}
       cancel-in-progress: false
-    runs-on: ubuntu-latest
+    runs-on: namespace-profile-linux-small
     steps:
       - name: "authenticate"
         id: "authenticate"
@@ -48,7 +48,7 @@ jobs:
     concurrency:
       group: pr-review-status-promote
       cancel-in-progress: false
-    runs-on: ubuntu-latest
+    runs-on: namespace-profile-linux-small
     steps:
       - name: "authenticate"
         id: "authenticate"

.github/workflows/projects.yml

@@ -14,7 +14,7 @@ jobs:
     concurrency:
       group: update-bugs-project-${{ github.event.issue.number }}
       cancel-in-progress: true
-    runs-on: ubuntu-latest
+    runs-on: namespace-profile-linux-small
     steps:
       - name: "authenticate"
         id: "authenticate"

.github/workflows/publish_pr.yml

@@ -15,7 +15,7 @@ permissions:
 
 jobs:
   publish:
-    runs-on: ubuntu-latest
+    runs-on: namespace-profile-linux-small
     steps:
       - name: Generate an Application repository access token
         id: gen_repo_token

.github/workflows/release-26.3.yaml

@@ -0,0 +1,56 @@
+name: Release 26.3
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  cancel-in-progress: false
+  group: release-26.3
+
+jobs:
+  release:
+    # guard for manual dispatch
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: namespace-profile-linux-default
+    timeout-minutes: 30
+    #env:
+    #  BUILD_NUMBER: ${{ github.run_number }}
+    steps:
+      - name: "environment"
+        run: |
+          echo "BUILD_NUMBER=$((129 + GITHUB_RUN_NUMBER))" >> "$GITHUB_ENV"
+          echo "BUILD_STARTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$GITHUB_ENV"
+
+      - name: "git / checkout"
+        uses: namespacelabs/nscloud-checkout-action@66f2dc6f6c42a8ac6c4e53473c4840006822831e # v9.0.1
+        with:
+          fetch-depth: 0
+
+      - uses: papermc/ci/setup-gradle@main
+
+      - uses: papermc/ci/build-paper@main
+
+      - if: ${{ !cancelled() }}
+        uses: papermc/ci/upload-event-data@main
+        with:
+          path: ${{ github.event_path }}
+
+      - if: ${{ !cancelled() }}
+        uses: papermc/ci/upload-test-results@main
+
+      - uses: papermc/ci/publish-fill@main
+        with:
+          fill_api_url: ${{ secrets.FILL_API_URL }}
+          fill_api_key: ${{ secrets.FILL_API_KEY }}
+
+      - uses: papermc/ci/publish-maven@main
+        with:
+          maven_username: ${{ secrets.ARTIFACTORY_USERNAME }}
+          maven_password: ${{ secrets.ARTIFACTORY_PASSWORD }}
+          maven_tasks: -PpublishDevBundle :paper-api:publish publishDevBundlePublicationToPaperReleasesRepository

.github/workflows/test_results.yaml

@@ -0,0 +1,24 @@
+name: Test Results
+
+on:
+  workflow_run:
+    workflows: [ "Build Paper" ]
+    types:
+      - completed
+
+permissions:
+  actions: read
+  checks: write
+
+jobs:
+  test-results:
+    name: Test Results
+    if: github.event.workflow_run.conclusion != 'skipped'
+    runs-on: namespace-profile-linux-small
+    steps:
+      - uses: papermc/ci/publish-test-results@main
+        with:
+          event: ${{ github.event.workflow_run.event }}
+          commit: ${{ github.event.workflow_run.head_sha }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          run_id: ${{ github.event.workflow_run.id }}

.github/workflows/test_results.yml

@@ -1,34 +0,0 @@
-name: Test Results
-
-on:
-  workflow_run:
-    workflows: [ "Build Paper" ]
-    types:
-      - completed
-permissions: { }
-
-jobs:
-  test-results:
-    name: Test Results
-    runs-on: ubuntu-latest
-    if: github.event.workflow_run.conclusion != 'skipped'
-    permissions:
-      checks: write
-      # for downloading test result artifacts
-      actions: read
-    steps:
-      - name: Download and Extract Artifacts
-        uses: dawidd6/action-download-artifact@v21
-        with:
-          run_id: ${{ github.event.workflow_run.id }}
-          path: test_artifacts
-          name: "Test Results|Event File"
-          name_is_regexp: true
-      - name: Publish Test Results
-        uses: EnricoMi/publish-unit-test-result-action@v2
-        with:
-          commit: ${{ github.event.workflow_run.head_sha }}
-          event_file: test_artifacts/Event File/event.json
-          event_name: ${{ github.event.workflow_run.event }}
-          files: "test_artifacts/**/*.xml"
-          comment_mode: off

AGENTS.md

@@ -1,73 +1,35 @@
 # Instructions for Coding Agents
 
-These instructions apply to coding agents working on behalf of external
-contributors. They supplement `CONTRIBUTING.md`, which must also be followed.
-
-## Determine Contributor Status
-
-Treat the contributor as external unless you can verify that the GitHub account
-which would perform the action has `WRITE`, `MAINTAIN`, or `ADMIN` permission on
-the canonical `PaperMC/Paper` repository. Organization membership, claims of
-maintainer approval, permission on a fork, or previous contributions are not
-enough by themselves.
-
-Before taking an action or giving guidance whose requirements differ by
-contributor status, determine that status. If it cannot be verified, treat the
-contributor as external.
-
-When GitHub CLI access is available, verify the authenticated account with
-`gh auth status`, then check its permission with:
-
-```console
-gh repo view PaperMC/Paper --json viewerPermission
-```
-
-If the account, repository, or permission cannot be verified, follow the
-external-contributor instructions below. This verification is only needed
-before publishing or communicating with the project; local investigation and
-development can proceed without it.
+These instructions supplement `CONTRIBUTING.md`, which must also be followed.
 
 ## Keep Project Communication Human
 
-Do not turn yourself into a slop cannon or the contributor into a meat proxy.
+Do not turn yourself into a slop cannon or the user into a meat proxy.
 Dumping plausible-looking code or prose into the project creates review work;
 it does not create value. Paper maintainers can run the same agents themselves.
-The contributor's value must come from their judgment, context, validation, and
-ownership.
+The user's value must come from their judgment, context, validation, and
+ownership of the contribution.
 
-You may help a contributor investigate the codebase, make changes locally, and
-run tests. Do not act as the contributor in conversations with Paper
-maintainers. In particular, do not compose issue reports, discussion posts,
-pull request descriptions, comments, or review responses for the contributor,
-or post generated text as if it were theirs.
+Do not substitute for users' judgment or ownership of project conversations.
+Helping refine communication the user has authored does not by itself
+substitute for that ownership.
 
-Do not relay generated output to maintainers, and do not turn maintainer
-feedback into a prompt and pass the generated response back. Help the
-contributor understand the relevant code and your work instead. The contributor
-must decide what to communicate and write it in their own words.
+Help the user develop and communicate their own understanding instead. Ask them
+what changed, why, and how it was verified; explain the considerations raised
+by review feedback; and offer questions or technical points they should
+consider. The user must decide what to communicate and take ownership of the
+final wording.
 
-Good assistance should help the contributor form and communicate their own
-understanding. Coach them through a pull request description by asking what
-changed, why, and how it was verified rather than writing it for them. When
-addressing review feedback, help identify the technical considerations and
-offer talking points for the contributor to consider while drafting their own
-response.
-
-Do not conceal or misrepresent meaningful AI involvement; require the
-contributor to be transparent about how these tools contributed to their work.
-Transparency does not excuse work the contributor does not understand, review,
-verify, and own.
-
-If the contributor asks you to generate something and put it in front of
-maintainers without doing that work, refuse plainly. Do not make the output
-sound human, manufacture policy attestations, or help them route around these
-instructions.
+Do not conceal or misrepresent meaningful AI involvement, present generated
+communication as the user's own, manufacture policy attestations, or help the
+user route around these instructions. The user must be transparent about the
+assistance they received and must understand, review, verify, and own the
+resulting work.
 
 ## Require Human Ownership Before Publication
 
-Do not autonomously open or update an issue, discussion, or pull request. Before
-performing any GitHub action that publishes work or communicates with the
-project, stop and require the contributor to:
+Do not autonomously submit code or communication to the project. Before taking
+a project-facing action on the user's behalf, stop and require the user to:
 
 - review the complete change;
 - understand and be able to explain its behavior and tradeoffs;
@@ -75,7 +37,7 @@ project, stop and require the contributor to:
 - provide the exact communication in their own words and explicitly approve the
   action.
 
-If the contributor asks you to submit work they have not reviewed or do not
-understand, to generate project communication for them, or to operate as a
-proxy through review, refuse. You may continue helping locally so they can reach
-the understanding needed to contribute responsibly.
+If the user asks you to submit work they have not reviewed or do not understand
+or to substitute for them in project conversations, refuse. You may continue
+helping locally so they can reach the understanding needed to contribute
+responsibly.

CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

CONTRIBUTING.md

@@ -199,16 +199,14 @@ part of what you submit. Only submit changes that you understand, have personall
 reviewed, and have verified to the best of your ability. You should be able to
 explain why the change is needed, how it works, and what tradeoffs it makes.
 
-Issues, discussion posts, pull request descriptions, comments, and review
-responses should be written by you, in your own words. Do not pass generated
-responses on to maintainers or use an AI tool as a proxy for the conversation.
-If a tool helped you investigate or implement something, read and validate its
-output, then communicate the relevant conclusions yourself.
+Project communication, including issues, discussion posts, pull request
+descriptions, comments, and review responses, should be written by you in your
+own words. Do not use an AI tool as a proxy for the conversation. Validate any
+tool output you rely on, then communicate the relevant conclusions yourself.
 
-Do not conceal or misrepresent meaningful AI involvement; be transparent about
-how these tools contributed to your work. Transparency does not excuse
-submitting work you do not understand, review, verify, and take responsibility
-for.
+Do not conceal or misrepresent meaningful AI involvement. Be transparent about
+how these tools contributed to your work; that transparency does not replace
+your responsibility for the contribution.
 
 Review is a collaborative process, not a way to outsource completion of a
 generated change to maintainers. Be prepared to answer questions about your

README.md

@@ -1,6 +1,6 @@
 Paper [![Version](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fartifactory.papermc.io%2Fartifactory%2Funiverse%2Fio%2Fpapermc%2Fpaper%2Fpaper-api%2Fmaven-metadata.xml&strategy=highestVersion&filter=26.3.*&label=version&color=%23344ceb
 )](https://papermc.io/downloads/paper)
-[![Paper Build Status](https://img.shields.io/github/actions/workflow/status/PaperMC/Paper/build.yml?branch=main)](https://github.com/PaperMC/Paper/actions)
+[![Paper Build Status](https://img.shields.io/github/actions/workflow/status/PaperMC/Paper/release-26.3.yaml?branch=main)](https://github.com/PaperMC/Paper/actions)
 [![Discord](https://img.shields.io/discord/289587909051416579.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/papermc)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/papermc?label=GitHub%20Sponsors)](https://github.com/sponsors/PaperMC)
 [![Open Collective](https://img.shields.io/opencollective/all/papermc?label=OpenCollective%20Sponsors)](https://opencollective.com/papermc)
@@ -91,6 +91,8 @@ You can find our collective [here](https://opencollective.com/papermc), or you c
 Special Thanks To:
 -------------
 
+[![CI powered by namespace badge](https://assets.papermc.io/sponsors/namespace-oss-badge.svg)](https://namespace.so/github-actions/?utm_source=oss&utm_campaign=papermc)
+
 [![YourKit-Logo](https://www.yourkit.com/images/yklogo.png)](https://www.yourkit.com/)
 
 [YourKit](https://www.yourkit.com/), makers of the outstanding java profiler, support open source projects of all kinds with their full featured [Java](https://www.yourkit.com/java/profiler) and [.NET](https://www.yourkit.com/.net/profiler) application profilers. We thank them for granting Paper an OSS license so that we can make our software the best it can be.

build-data/paper.at

@@ -5,6 +5,7 @@ private-f net.minecraft.server.MinecraftServer connection
 private-f net.minecraft.server.MinecraftServer levels
 private-f net.minecraft.world.item.ItemStack components
 private-f net.minecraft.world.item.ItemStack item
+private-f net.minecraft.world.item.crafting.RecipeManager learnableRecipes
 private-f net.minecraft.world.level.block.entity.BeehiveBlockEntity stored
 protected net.minecraft.world.entity.LivingEntity skipDropExperience
 protected net.minecraft.world.level.Level thread
@@ -24,6 +25,7 @@ public net.minecraft.network.Connection channel
 public net.minecraft.network.chat.contents.TranslatableContents PRIMITIVE_ARG_CODEC
 public net.minecraft.network.protocol.game.ClientboundBlockEntityDataPacket <init>(Lnet/minecraft/core/BlockPos;Lnet/minecraft/world/level/block/entity/BlockEntityType;Lnet/minecraft/nbt/CompoundTag;)V
 public net.minecraft.network.syncher.SynchedEntityData getItem(Lnet/minecraft/network/syncher/EntityDataAccessor;)Lnet/minecraft/network/syncher/SynchedEntityData$DataItem;
+public net.minecraft.resources.RegistryOps <init>(Lcom/mojang/serialization/DynamicOps;Lnet/minecraft/resources/RegistryOps$RegistryInfoLookup;)V
 public net.minecraft.resources.RegistryOps lookupProvider
 public net.minecraft.resources.RegistryOps$HolderLookupAdapter
 public net.minecraft.server.Main forceUpgrade(Lnet/minecraft/world/level/storage/LevelStorageSource$LevelStorageAccess;Lcom/mojang/datafixers/DataFixer;ZLjava/util/function/BooleanSupplier;Lnet/minecraft/core/RegistryAccess;Z)V
@@ -166,6 +168,8 @@ public net.minecraft.world.entity.Display$TextDisplay setText(Lnet/minecraft/net
 public net.minecraft.world.entity.Display$TextDisplay setTextOpacity(B)V
 public net.minecraft.world.entity.Entity DATA_TICKS_FROZEN
 public net.minecraft.world.entity.Entity FLAG_INVISIBLE
+public net.minecraft.world.entity.Entity getAirDrag()F
+public net.minecraft.world.entity.Entity getDefaultGravity()D
 public net.minecraft.world.entity.Entity getEncodeId()Ljava/lang/String;
 public net.minecraft.world.entity.Entity getFireImmuneTicks()I
 public net.minecraft.world.entity.Entity getSharedFlag(I)Z
@@ -392,6 +396,7 @@ public net.minecraft.world.entity.npc.villager.Villager updateDemand()V
 public net.minecraft.world.entity.npc.villager.Villager updateSpecialPrices(Lnet/minecraft/world/entity/player/Player;)V
 public net.minecraft.world.entity.npc.wanderingtrader.WanderingTrader getWanderTarget()Lnet/minecraft/core/BlockPos;
 public net.minecraft.world.entity.player.Inventory equipment
+public net.minecraft.world.entity.player.Player canCriticalAttack(Lnet/minecraft/world/entity/Entity;)Z
 public net.minecraft.world.entity.player.Player closeContainer()V
 public net.minecraft.world.entity.player.Player enchantmentSeed
 public net.minecraft.world.entity.player.Player hurtDir
@@ -649,6 +654,7 @@ public net.minecraft.world.level.storage.SavedDataStorage cache
 public net.minecraft.world.level.storage.TagValueInput input
 public net.minecraft.world.level.storage.loot.providers.number.ints.ResolvableInt$Reference getProvider(Lnet/minecraft/world/level/storage/loot/LootContext;)Ljava/util/Optional;
 public net.minecraft.world.scores.criteria.ObjectiveCriteria CRITERIA_CACHE
+public net.minecraft.world.timeline.Timeline tracks
 public-f net.minecraft.server.MinecraftServer storageSource
 public-f net.minecraft.server.ServerAdvancementManager advancements
 public-f net.minecraft.server.dedicated.DedicatedServer serverLinks

build.gradle.kts

@@ -4,7 +4,7 @@ import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 import org.gradle.api.tasks.testing.logging.TestLogEvent
 
 plugins {
-    id("io.papermc.paperweight.core") version "2.0.0-beta.23" apply false
+    id("io.papermc.paperweight.core") version "2.0.0-beta.24" apply false
 }
 
 subprojects {

gradle.properties

@@ -3,7 +3,7 @@ mcVersion=26.3
 # This is the current API version for use in (paper-)plugin.yml files
 # During snapshot cycles this should be the anticipated version of the release target
 apiVersion=26.3
-channel=ALPHA
+channel=STABLE
 
 # Set to true while updating Minecraft version
 updatingMinecraft=false

gradle/wrapper/gradle-wrapper.properties

@@ -1,7 +1,9 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.0-bin.zip
 networkTimeout=10000
+retries=0
+retryBackOffMs=500
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

gradlew

@@ -20,7 +20,7 @@
 
 ##############################################################################
 #
-#   Gradle start up script for POSIX generated by Gradle.
+#   gradlew start up script for POSIX generated by Gradle.
 #
 #   Important for running:
 #
@@ -29,7 +29,7 @@
 #       bash, then to run this script, type that shell name before the whole
 #       command line, like:
 #
-#           ksh Gradle
+#           ksh gradlew
 #
 #       Busybox and similar reduced shells will NOT work, because this script
 #       requires all of these POSIX shell features:
@@ -57,7 +57,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/2d6327017519d23b96af35865dc997fcb544fb40/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/3d91ce3b8caaf77ad09f381f43615b715b53f72c/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.

gradlew.bat

@@ -19,12 +19,39 @@
 @if "%DEBUG%"=="" @echo off
 @rem ##########################################################################
 @rem
-@rem  Gradle startup script for Windows
+@rem  gradlew startup script for Windows
 @rem
 @rem ##########################################################################
 
-@rem Set local scope for the variables with windows NT shell
-if "%OS%"=="Windows_NT" setlocal
+@rem Set local scope for the variables, and ensure extensions are enabled
+setlocal EnableExtensions
+
+@rem Catch executions from older scripts and ensure they exit cleanly.
+@rem This can be removed once we can be reasonably confident that few people
+@rem will be migrating directly to this new wrapper.
+goto afterSafetyNet
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+goto exitWithErrorLevel
+:afterSafetyNet
 
 set DIRNAME=%~dp0
 if "%DIRNAME%"=="" set DIRNAME=.
@@ -45,13 +72,14 @@ set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
 if %ERRORLEVEL% equ 0 goto execute
 
-echo. 1>&2
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
-echo. 1>&2
-echo Please set the JAVA_HOME variable in your environment to match the 1>&2
-echo location of your Java installation. 1>&2
+1>&2 echo.
+1>&2 echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+1>&2 echo.
+1>&2 echo Please set the JAVA_HOME variable in your environment to match the
+1>&2 echo location of your Java installation.
 
-goto fail
+"%COMSPEC%" /c exit 1
+goto exitWithErrorLevel
 
 :findJavaFromJavaHome
 set JAVA_HOME=%JAVA_HOME:"=%
@@ -59,35 +87,26 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
 if exist "%JAVA_EXE%" goto execute
 
-echo. 1>&2
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
-echo. 1>&2
-echo Please set the JAVA_HOME variable in your environment to match the 1>&2
-echo location of your Java installation. 1>&2
+1>&2 echo.
+1>&2 echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
+1>&2 echo.
+1>&2 echo Please set the JAVA_HOME variable in your environment to match the
+1>&2 echo location of your Java installation.
 
-goto fail
+"%COMSPEC%" /c exit 1
+goto exitWithErrorLevel
 
 :execute
 @rem Setup the command line
 
 
 
-@rem Execute Gradle
-"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %*
+@rem Execute gradlew
+@rem endlocal doesn't take effect until after the line is parsed and variables are expanded
+@rem which allows us to clear the local environment before executing the java command
+endlocal & "%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %* & call :exitWithErrorLevel & goto exitWithErrorLevel
 
-:end
-@rem End local scope for the variables with windows NT shell
-if %ERRORLEVEL% equ 0 goto mainEnd
-
-:fail
-rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
-rem the _cmd.exe /c_ return code!
-set EXIT_CODE=%ERRORLEVEL%
-if %EXIT_CODE% equ 0 set EXIT_CODE=1
-if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
-exit /b %EXIT_CODE%
-
-:mainEnd
-if "%OS%"=="Windows_NT" endlocal
-
-:omega
+@rem This label must not be changed. We rely on old scripts being able to jump to this point.
+:exitWithErrorLevel
+@rem Use "%COMSPEC%" /c exit to allow operators to work properly in scripts
+"%COMSPEC%" /c exit %ERRORLEVEL%

paper-api/build.gradle.kts

@@ -28,11 +28,11 @@ val bungeeCordChatVersion = "1.21-R0.2-deprecated+build.21"
 val slf4jVersion = "2.0.17"
 val log4jVersion = "2.26.0"
 
-val apiAndDocs: Configuration by configurations.creating
+val apiAndDocs: Configuration = configurations.create("apiAndDocs")
 configurations.api {
     extendsFrom(apiAndDocs)
 }
-val javadocSourcepath: Configuration by configurations.creating {
+val javadocSourcepath: Configuration = configurations.create("javadocSourcepath") {
     attributes {
         attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category.DOCUMENTATION))
         attribute(Bundling.BUNDLING_ATTRIBUTE, objects.named(Bundling.EXTERNAL))
@@ -251,7 +251,7 @@ tasks.compileTestJava {
     options.compilerArgs.add("-parameters")
 }
 
-val scanJarForBadCalls by tasks.registering(io.papermc.paperweight.tasks.ScanJarForBadCalls::class) {
+val scanJarForBadCalls = tasks.register<io.papermc.paperweight.tasks.ScanJarForBadCalls>("scanJarForBadCalls") {
     badAnnotations.add("Lio/papermc/paper/annotation/DoNotUse;")
     jarToScan.set(tasks.jar.flatMap { it.archiveFile })
     classpath.from(configurations.compileClasspath)

paper-api/src/generated/java/io/papermc/paper/registry/keys/TimelineKeys.java

@@ -0,0 +1,68 @@
+package io.papermc.paper.registry.keys;
+
+import static net.kyori.adventure.key.Key.key;
+
+import io.papermc.paper.annotation.GeneratedClass;
+import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.TypedKey;
+import io.papermc.paper.world.Timeline;
+import net.kyori.adventure.key.Key;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Vanilla keys for {@link RegistryKey#TIMELINE}.
+ *
+ * @apiNote The fields provided here are a direct representation of
+ * what is available from the vanilla game source. They may be
+ * changed (including removals) on any Minecraft version
+ * bump, so cross-version compatibility is not provided on the
+ * same level as it is on most of the other API.
+ */
+@SuppressWarnings({
+        "unused",
+        "SpellCheckingInspection"
+})
+@NullMarked
+@GeneratedClass
+public final class TimelineKeys {
+    /**
+     * {@code minecraft:day}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<Timeline> DAY = create(key("day"));
+
+    /**
+     * {@code minecraft:early_game}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<Timeline> EARLY_GAME = create(key("early_game"));
+
+    /**
+     * {@code minecraft:moon}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<Timeline> MOON = create(key("moon"));
+
+    /**
+     * {@code minecraft:villager_schedule}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<Timeline> VILLAGER_SCHEDULE = create(key("villager_schedule"));
+
+    private TimelineKeys() {
+    }
+
+    /**
+     * Creates a typed key for {@link Timeline} in the registry {@code minecraft:timeline}.
+     *
+     * @param key the value's key in the registry
+     * @return a new typed key
+     */
+    public static TypedKey<Timeline> create(final Key key) {
+        return TypedKey.create(RegistryKey.TIMELINE, key);
+    }
+}

paper-api/src/generated/java/io/papermc/paper/registry/keys/WorldClockKeys.java

@@ -0,0 +1,54 @@
+package io.papermc.paper.registry.keys;
+
+import static net.kyori.adventure.key.Key.key;
+
+import io.papermc.paper.annotation.GeneratedClass;
+import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.TypedKey;
+import io.papermc.paper.world.WorldClock;
+import net.kyori.adventure.key.Key;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Vanilla keys for {@link RegistryKey#WORLD_CLOCK}.
+ *
+ * @apiNote The fields provided here are a direct representation of
+ * what is available from the vanilla game source. They may be
+ * changed (including removals) on any Minecraft version
+ * bump, so cross-version compatibility is not provided on the
+ * same level as it is on most of the other API.
+ */
+@SuppressWarnings({
+        "unused",
+        "SpellCheckingInspection"
+})
+@NullMarked
+@GeneratedClass
+public final class WorldClockKeys {
+    /**
+     * {@code minecraft:overworld}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<WorldClock> OVERWORLD = create(key("overworld"));
+
+    /**
+     * {@code minecraft:the_end}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<WorldClock> THE_END = create(key("the_end"));
+
+    private WorldClockKeys() {
+    }
+
+    /**
+     * Creates a typed key for {@link WorldClock} in the registry {@code minecraft:world_clock}.
+     *
+     * @param key the value's key in the registry
+     * @return a new typed key
+     */
+    public static TypedKey<WorldClock> create(final Key key) {
+        return TypedKey.create(RegistryKey.WORLD_CLOCK, key);
+    }
+}

paper-api/src/generated/java/io/papermc/paper/registry/keys/tags/TimelineTagKeys.java

@@ -0,0 +1,68 @@
+package io.papermc.paper.registry.keys.tags;
+
+import static net.kyori.adventure.key.Key.key;
+
+import io.papermc.paper.annotation.GeneratedClass;
+import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.tag.TagKey;
+import io.papermc.paper.world.Timeline;
+import net.kyori.adventure.key.Key;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Vanilla tag keys for {@link RegistryKey#TIMELINE}.
+ *
+ * @apiNote The fields provided here are a direct representation of
+ * what is available from the vanilla game source. They may be
+ * changed (including removals) on any Minecraft version
+ * bump, so cross-version compatibility is not provided on the
+ * same level as it is on most of the other API.
+ */
+@SuppressWarnings({
+        "unused",
+        "SpellCheckingInspection"
+})
+@NullMarked
+@GeneratedClass
+public final class TimelineTagKeys {
+    /**
+     * {@code #minecraft:in_end}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TagKey<Timeline> IN_END = create(key("in_end"));
+
+    /**
+     * {@code #minecraft:in_nether}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TagKey<Timeline> IN_NETHER = create(key("in_nether"));
+
+    /**
+     * {@code #minecraft:in_overworld}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TagKey<Timeline> IN_OVERWORLD = create(key("in_overworld"));
+
+    /**
+     * {@code #minecraft:universal}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TagKey<Timeline> UNIVERSAL = create(key("universal"));
+
+    private TimelineTagKeys() {
+    }
+
+    /**
+     * Creates a tag key for {@link Timeline} in the registry {@code minecraft:timeline}.
+     *
+     * @param key the tag key's key
+     * @return a new tag key
+     */
+    public static TagKey<Timeline> create(final Key key) {
+        return TagKey.create(RegistryKey.TIMELINE, key);
+    }
+}

paper-api/src/main/java/com/destroystokyo/paper/event/block/TNTPrimeEvent.java

@@ -1,6 +1,7 @@
 package com.destroystokyo.paper.event.block;
 
 import org.bukkit.Material;
+import org.bukkit.Warning;
 import org.bukkit.block.Block;
 import org.bukkit.enchantments.Enchantment;
 import org.bukkit.entity.Entity;
@@ -23,6 +24,7 @@ import org.jetbrains.annotations.Nullable;
  * @deprecated use {@link org.bukkit.event.block.TNTPrimeEvent}
  */
 @Deprecated(forRemoval = true, since = "1.19.4")
+@Warning(propagate = false)
 public class TNTPrimeEvent extends BlockEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java

@@ -13,6 +13,8 @@ import org.jspecify.annotations.NullMarked;
  * Called when sending {@link Suggestions} to the client. Will be called asynchronously if a plugin
  * marks the {@link com.destroystokyo.paper.event.server.AsyncTabCompleteEvent} event handled asynchronously,
  * otherwise called synchronously.
+ * <p>
+ * If the suggestions are empty after this event has been called, nothing will be sent to the client.
  */
 @NullMarked
 public class AsyncPlayerSendSuggestionsEvent extends PlayerEvent implements Cancellable {
@@ -51,6 +53,8 @@ public class AsyncPlayerSendSuggestionsEvent extends PlayerEvent implements Canc
 
     /**
      * Sets the suggestions to be sent to client.
+     * <p>
+     * Empty suggestions are never sent to the client.
      *
      * @param suggestions suggestions
      */

paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java

@@ -18,10 +18,11 @@ import org.jetbrains.annotations.NotNull;
  * This is done at Plugin Enable time after commands have been registered, but may also
  * run at a later point in the server lifetime due to plugins, a server reload, etc.</p>
  *
- * @deprecated For removal, use the new brigadier api.
+ * @deprecated this event has been superseded by the Commands API and will be removed in a future release.
+ * Listen to {@link io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents#COMMANDS} instead
  */
 @Deprecated(since = "1.20.6")
-@Warning(reason = "This event has been superseded by the Commands API and will be removed in a future release. Listen to LifecycleEvents.COMMANDS instead.", value = true)
+@Warning(value = true, propagate = false)
 public class CommandRegisteredEvent<S extends com.destroystokyo.paper.brigadier.BukkitBrigadierCommandSource> extends ServerEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/com/destroystokyo/paper/event/entity/ProjectileCollideEvent.java

@@ -1,5 +1,6 @@
 package com.destroystokyo.paper.event.entity;
 
+import org.bukkit.Warning;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Projectile;
 import org.bukkit.event.Cancellable;
@@ -17,6 +18,7 @@ import org.jetbrains.annotations.NotNull;
  * @deprecated Deprecated, use {@link org.bukkit.event.entity.ProjectileHitEvent} and check if there is a hit entity
  */
 @Deprecated(since = "1.19.3")
+@Warning(propagate = false)
 public class ProjectileCollideEvent extends EntityEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/com/destroystokyo/paper/event/inventory/PrepareGrindstoneEvent.java

@@ -14,7 +14,7 @@ import org.jetbrains.annotations.Nullable;
  * @deprecated use {@link org.bukkit.event.inventory.PrepareGrindstoneEvent}
  */
 @Deprecated(since = "1.16.1")
-@Warning
+@Warning(propagate = false)
 public class PrepareGrindstoneEvent extends PrepareResultEvent {
 
     @ApiStatus.Internal

paper-api/src/main/java/com/destroystokyo/paper/event/player/IllegalPacketEvent.java

@@ -1,5 +1,6 @@
 package com.destroystokyo.paper.event.player;
 
+import org.bukkit.Warning;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
@@ -11,6 +12,7 @@ import org.jetbrains.annotations.Nullable;
  * @deprecated Not used
  */
 @Deprecated(since = "1.16.4", forRemoval = true)
+@Warning(value = true, propagate = false)
 public class IllegalPacketEvent extends PlayerEvent {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/com/destroystokyo/paper/event/player/PlayerAttackEntityCooldownResetEvent.java

@@ -1,5 +1,6 @@
 package com.destroystokyo.paper.event.player;
 
+import org.bukkit.Warning;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
@@ -19,6 +20,7 @@ import org.jspecify.annotations.NullMarked;
  */
 @NullMarked
 @Deprecated(since = "26.1", forRemoval = true)
+@Warning(value = true, propagate = false)
 public class PlayerAttackEntityCooldownResetEvent extends PlayerEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/com/destroystokyo/paper/event/player/PlayerConnectionCloseEvent.java

@@ -1,6 +1,8 @@
 package com.destroystokyo.paper.event.player;
 
 import java.net.InetAddress;
+import java.net.InetSocketAddress;
+import java.net.SocketAddress;
 import java.util.UUID;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
@@ -41,10 +43,10 @@ public class PlayerConnectionCloseEvent extends Event {
 
     private final UUID playerUniqueId;
     private final String playerName;
-    private final InetAddress ipAddress;
+    private final SocketAddress ipAddress;
 
     @ApiStatus.Internal
-    public PlayerConnectionCloseEvent(final UUID playerUniqueId, final String playerName, final InetAddress ipAddress, final boolean async) {
+    public PlayerConnectionCloseEvent(final UUID playerUniqueId, final String playerName, final SocketAddress ipAddress, final boolean async) {
         super(async);
         this.playerUniqueId = playerUniqueId;
         this.playerName = playerName;
@@ -66,10 +68,20 @@ public class PlayerConnectionCloseEvent extends Event {
     }
 
     /**
-     * Returns the player's IP address.
+     * Returns the player's socket address.
+     */
+    public SocketAddress getSocketAddress() {
+        return this.ipAddress;
+    }
+
+    /**
+     * Returns the player's IP address, or the loopback address if the player
+     * is connecting through a Unix domain socket and the proxy has not
+     * forwarded the player's IP address yet.
      */
     public InetAddress getIpAddress() {
-        return this.ipAddress;
+        if (this.ipAddress instanceof InetSocketAddress inet) return inet.getAddress();
+        return InetAddress.getLoopbackAddress();
     }
 
     @Override

paper-api/src/main/java/com/destroystokyo/paper/event/server/PaperServerListPingEvent.java

@@ -58,7 +58,7 @@ public class PaperServerListPingEvent extends ServerListPingEvent implements Can
     @ApiStatus.Internal
     public PaperServerListPingEvent(@NotNull StatusClient client, @NotNull net.kyori.adventure.text.Component motd, int numPlayers, int maxPlayers,
                                     @NotNull String version, int protocolVersion, @Nullable CachedServerIcon favicon) {
-        super("", client.getAddress().getAddress(), motd, numPlayers, maxPlayers);
+        super("", client.getSocketAddress(), motd, numPlayers, maxPlayers);
         this.client = client;
         this.numPlayers = numPlayers;
         this.version = version;

paper-api/src/main/java/com/destroystokyo/paper/network/NetworkClient.java

@@ -1,6 +1,7 @@
 package com.destroystokyo.paper.network;
 
 import java.net.InetSocketAddress;
+import java.net.SocketAddress;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
@@ -15,6 +16,15 @@ public interface NetworkClient {
      *
      * @return The client's socket address
      */
+    SocketAddress getSocketAddress();
+
+    /**
+     * Returns an instance of {@link InetSocketAddress} associated with the
+     * client's socket address.
+     *
+     * @return The client's {@link InetSocketAddress}, or the loopback address
+     * if this is a Unix domain socket connection
+     */
     InetSocketAddress getAddress();
 
     /**

paper-api/src/main/java/io/papermc/paper/InternalAPIBridge.java

@@ -5,6 +5,7 @@ import com.destroystokyo.paper.util.VersionFetcher;
 import io.papermc.paper.command.brigadier.CommandSourceStack;
 import io.papermc.paper.datacomponent.item.ResolvableProfile;
 import io.papermc.paper.entity.poi.PoiType;
+import io.papermc.paper.persistence.PersistentDataKey;
 import io.papermc.paper.plugin.lifecycle.event.LifecycleEventManager;
 import io.papermc.paper.world.damagesource.CombatEntry;
 import io.papermc.paper.world.damagesource.FallLocationType;
@@ -13,6 +14,7 @@ import java.util.Set;
 import java.util.function.BooleanSupplier;
 import java.util.function.Function;
 import java.util.function.Predicate;
+import net.kyori.adventure.key.Key;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.flattener.ComponentFlattener;
 import net.kyori.adventure.util.Services;
@@ -25,12 +27,14 @@ import org.bukkit.command.CommandSender;
 import org.bukkit.damage.DamageEffect;
 import org.bukkit.damage.DamageSource;
 import org.bukkit.damage.DamageType;
+import org.bukkit.enchantments.EnchantmentOffer;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.EntityType;
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Pose;
 import org.bukkit.entity.SpawnCategory;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.persistence.PersistentDataType;
 import org.bukkit.plugin.Plugin;
 import org.bukkit.plugin.java.JavaPlugin;
 import org.jetbrains.annotations.ApiStatus;
@@ -69,14 +73,15 @@ public interface InternalAPIBridge {
     CombatEntry createCombatEntry(DamageSource damageSource, float damage, @Nullable FallLocationType fallLocationType, float fallDistance);
 
     /**
-     * Causes this predicate to be considered restricted.
-     * Applying this to a command node prevents this command from being executed from an
-     * unattended context, such as click events.
+     * Allows overriding default restricted check.
+     * Applying this to a command node forcefully prevents or permits this command to be
+     * executed from an unattended context, such as click events.
      *
-     * @param predicate wrapped predicate
+     * @param predicate  wrapped predicate
+     * @param restricted restricted status of the predicate
      * @return wrapped predicate
      */
-    Predicate<CommandSourceStack> restricted(Predicate<CommandSourceStack> predicate);
+    Predicate<CommandSourceStack> restricted(Predicate<CommandSourceStack> predicate, boolean restricted);
 
     ResolvableProfile defaultMannequinProfile();
 
@@ -121,4 +126,8 @@ public interface InternalAPIBridge {
     Component resolveWithContext(Component component, @Nullable CommandSender context, @Nullable Entity scoreboardSubject, boolean bypassPermissions) throws IOException;
 
     ComponentFlattener componentFlattener();
+
+    <C> PersistentDataKey<C> createPersistentDataKey(Key key, PersistentDataType<?, C> type);
+
+    @Nullable EnchantmentOffer[] rollEnchantmentOffers(ItemStack targetStack, int seed, int bookshelfCount, int offerAmount);
 }

paper-api/src/main/java/io/papermc/paper/chat/ChatRenderer.java

@@ -26,12 +26,12 @@ public interface ChatRenderer {
     Component render(Player source, Component sourceDisplayName, Component message, Audience viewer);
 
     /**
-     * Create a new instance of the default {@link ChatRenderer}.
+     * Gets the default {@link ChatRenderer}.
      *
-     * @return a new {@link ChatRenderer}
+     * @return the default {@link ChatRenderer}
      */
     static ChatRenderer defaultRenderer() {
-        return new ViewerUnawareImpl.Default((source, sourceDisplayName, message) -> Component.translatable("chat.type.text", sourceDisplayName, message));
+        return ViewerUnawareImpl.Default.INSTANCE;
     }
 
     @ApiStatus.Internal

paper-api/src/main/java/io/papermc/paper/chat/ViewerUnawareImpl.java

@@ -5,13 +5,11 @@ import net.kyori.adventure.text.Component;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;
 
 @ApiStatus.Internal
 @NullMarked
 sealed class ViewerUnawareImpl implements ChatRenderer, ChatRenderer.ViewerUnaware permits ViewerUnawareImpl.Default {
     private final ViewerUnaware unaware;
-    private @Nullable Component message;
 
     ViewerUnawareImpl(final ViewerUnaware unaware) {
         this.unaware = unaware;
@@ -24,13 +22,12 @@ sealed class ViewerUnawareImpl implements ChatRenderer, ChatRenderer.ViewerUnawa
 
     @Override
     public Component render(final Player source, final Component sourceDisplayName, final Component message) {
-        if (this.message == null) {
-            this.message = this.unaware.render(source, sourceDisplayName, message);
-        }
-        return this.message;
+        return this.unaware.render(source, sourceDisplayName, message);
     }
 
     static final class Default extends ViewerUnawareImpl implements ChatRenderer.Default {
+        static final ViewerUnawareImpl.Default INSTANCE = new ViewerUnawareImpl.Default((source, sourceDisplayName, message) -> Component.translatable("chat.type.text", sourceDisplayName, message));
+
         Default(final ViewerUnaware unaware) {
             super(unaware);
         }

paper-api/src/main/java/io/papermc/paper/command/brigadier/BasicCommand.java

@@ -1,5 +1,6 @@
 package io.papermc.paper.command.brigadier;
 
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
 import java.util.Collection;
 import java.util.Collections;
 import org.bukkit.command.CommandSender;
@@ -20,7 +21,7 @@ public interface BasicCommand {
      * @param args the arguments of the command ignoring repeated spaces
      */
     @ApiStatus.OverrideOnly
-    void execute(CommandSourceStack commandSourceStack, String[] args);
+    void execute(CommandSourceStack commandSourceStack, String[] args) throws CommandSyntaxException;
 
     /**
      * Suggests possible completions for the given command {@link CommandSourceStack} and arguments.

paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandSourceStack.java

@@ -1,8 +1,14 @@
 package io.papermc.paper.command.brigadier;
 
+import com.google.common.base.Preconditions;
 import com.mojang.brigadier.RedirectModifier;
 import com.mojang.brigadier.exceptions.CommandSyntaxException;
 import com.mojang.brigadier.tree.CommandNode;
+import net.kyori.adventure.pointer.Pointered;
+import net.kyori.adventure.text.ComponentLike;
+import net.kyori.adventure.text.minimessage.MiniMessage;
+import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
+import org.bukkit.GameRules;
 import org.bukkit.Location;
 import org.bukkit.command.CommandSender;
 import org.bukkit.entity.Entity;
@@ -81,4 +87,123 @@ public interface CommandSourceStack {
      * @see com.mojang.brigadier.builder.ArgumentBuilder#fork(CommandNode, RedirectModifier)
      */
     CommandSourceStack withExecutor(Entity executor);
+
+    /**
+     * Sends a system message to the {@link #getExecutor()} if it is a {@link Player},
+     * otherwise sends a system message to the {@link #getSender()}.
+     *
+     * @param message the message to send
+     * @throws IllegalArgumentException if the message is null
+     */
+    void sendReply(ComponentLike message);
+
+    /**
+     * Sends a system message with the MiniMessage format to the {@link #getExecutor()}
+     * if it is a {@link Player}, otherwise sends it to the {@link #getSender()}.
+     *
+     * <p>See <a href="https://docs.papermc.io/adventure/minimessage/">MiniMessage docs</a> and
+     * <a href="https://docs.papermc.io/adventure/minimessage/dynamic-replacements/">MiniMessage Placeholders docs</a>
+     * for more information on the format.</p>
+     *
+     * <p>This method provides the target of the system message as a {@link net.kyori.adventure.pointer.Pointered}
+     * to the MiniMessage {@link MiniMessage#deserialize(String, Pointered, TagResolver...)} method.</p>
+     *
+     * @param message the MiniMessage message to send
+     * @param resolvers resolvers to use
+     * @throws IllegalArgumentException if the message is null
+     */
+    default void sendRichReply(final String message, final TagResolver... resolvers) {
+        Preconditions.checkArgument(message != null, "message cannot be null.");
+        this.sendReply(MiniMessage.miniMessage().deserialize(
+            message,
+            this.getExecutor() instanceof final Player player ? player : this.getSender(),
+            resolvers
+        ));
+    }
+
+    /**
+     * Sends a system message to the {@link #getSender()}, admins, and console indicating successful command execution
+     * according to vanilla semantics.
+     *
+     * <p>This currently includes checking for environments with suppressed output,
+     * {@link GameRules#SEND_COMMAND_FEEDBACK}, and {@link GameRules#LOG_ADMIN_COMMANDS}.</p>
+     *
+     * @param message the message to send
+     * @param allowInformingAdmins whether admins and console may be informed of this success
+     * @throws IllegalArgumentException if the message is null
+     */
+    void sendSuccess(ComponentLike message, boolean allowInformingAdmins);
+
+    /**
+     * Sends a system message to the {@link #getSender()}, admins, and console indicating successful command execution
+     * according to vanilla semantics. This method informs admins and the console of this success.
+     *
+     * <p>This currently includes checking for environments with suppressed output,
+     * {@link GameRules#SEND_COMMAND_FEEDBACK}, and {@link GameRules#LOG_ADMIN_COMMANDS}.</p>
+     *
+     * @param message the message to send
+     * @see #sendSuccess(ComponentLike, boolean) to disable if admins and console should be informed
+     * @throws IllegalArgumentException if the message is null
+     */
+    default void sendSuccess(final ComponentLike message) {
+        this.sendSuccess(message, true);
+    }
+
+    /**
+     * Sends a system message with the MiniMessage format to the {@link #getSender()}, admins, and console indicating
+     * successful command execution according to vanilla semantics. This method informs admins and the console of
+     * this success.
+     *
+     * <p>This currently includes checking for environments with suppressed output,
+     * {@link GameRules#SEND_COMMAND_FEEDBACK}, and {@link GameRules#LOG_ADMIN_COMMANDS}.</p>
+     *
+     * <p>See <a href="https://docs.papermc.io/adventure/minimessage/">MiniMessage docs</a> and
+     * <a href="https://docs.papermc.io/adventure/minimessage/dynamic-replacements/">MiniMessage Placeholders docs</a>
+     * for more information on the format.</p>
+     *
+     * <p>This method provides the {@link CommandSender} of this command as a {@link net.kyori.adventure.pointer.Pointered}
+     * to the MiniMessage {@link MiniMessage#deserialize(String, Pointered, TagResolver...)} method.</p>
+     *
+     * @param message the MiniMessage message to send
+     * @param resolvers resolvers to use
+     * @see #sendSuccess(ComponentLike, boolean) to disable if admins and console should be informed
+     * @throws IllegalArgumentException if the message is null
+     */
+    default void sendRichSuccess(final String message, final TagResolver... resolvers) {
+        Preconditions.checkArgument(message != null, "message cannot be null.");
+        this.sendSuccess(MiniMessage.miniMessage().deserialize(message, this.getSender(), resolvers), true);
+    }
+
+    /**
+     * Sends a system message indicating a failed command execution to the {@link #getSender()}.
+     * Does not apply red styling to the message as vanilla does to allow for custom failure message styling.
+     *
+     * <p>Respects vanilla semantics for accepting failure output and suppressed output environments.</p>
+     *
+     * @param message the message to send
+     * @throws IllegalArgumentException if the message is null
+     */
+    void sendFailure(ComponentLike message);
+
+    /**
+     * Sends a system message with the MiniMessage format indicating a failed command execution to the{@link #getSender()}.
+     * Does not apply red styling to the message as vanilla does to allow for custom failure message styling.
+     *
+     * <p>Respects vanilla semantics for accepting failure output and suppressed output environments.</p>
+     *
+     * <p>See <a href="https://docs.papermc.io/adventure/minimessage/">MiniMessage docs</a> and
+     * <a href="https://docs.papermc.io/adventure/minimessage/dynamic-replacements/">MiniMessage Placeholders docs</a>
+     * for more information on the format.</p>
+     *
+     * <p>This method provides the {@link CommandSender} of this command as a {@link net.kyori.adventure.pointer.Pointered}
+     * to the MiniMessage {@link MiniMessage#deserialize(String, Pointered, TagResolver...)} method.</p>
+     *
+     * @param message the MiniMessage message to send
+     * @param resolvers resolvers to use
+     * @throws IllegalArgumentException if the message is null
+     */
+    default void sendRichFailure(final String message, final TagResolver... resolvers) {
+        Preconditions.checkArgument(message != null, "message cannot be null.");
+        this.sendFailure(MiniMessage.miniMessage().deserialize(message, this.getSender(), resolvers));
+    }
 }

paper-api/src/main/java/io/papermc/paper/command/brigadier/Commands.java

@@ -97,7 +97,23 @@ public interface Commands extends Registrar {
      * @return a new predicate with restricted execution behavior
      */
     static Predicate<CommandSourceStack> restricted(final Predicate<CommandSourceStack> predicate) {
-        return InternalAPIBridge.get().restricted(predicate);
+        return InternalAPIBridge.get().restricted(predicate, true);
+    }
+
+    /**
+     * Creates an unrestricted {@link Predicate} that wraps the given predicate.
+     * <p>
+     * A restricted predicate prevents execution in unattended contexts, such as from chat click events.
+     * Unrestricting prevents the warning shown on the client before executing the command.
+     * <p>
+     * This is used by vanilla to prevent invocation of sensitive commands (like op) from
+     * players without their knowledge.
+     *
+     * @param predicate the original predicate to wrap
+     * @return a new predicate with unrestricted execution behavior
+     */
+    static Predicate<CommandSourceStack> unrestricted(final Predicate<CommandSourceStack> predicate) {
+        return InternalAPIBridge.get().restricted(predicate, false);
     }
 
     /**

paper-api/src/main/java/io/papermc/paper/connection/PlayerConnection.java

@@ -41,6 +41,8 @@ public interface PlayerConnection {
     /**
      * Gets the real client address of the player. If the connection is behind a proxy,
      * this will be the actual player’s IP address extracted from the proxy handshake.
+     * If the player is connecting through a Unix domain socket and the proxy has not
+     * forwarded the player's IP address yet, this will be the loopback address.
      *
      * @return the client {@link InetSocketAddress}
      */

paper-api/src/main/java/io/papermc/paper/entity/PlayerPostEffects.java

@@ -0,0 +1,64 @@
+package io.papermc.paper.entity;
+
+import java.util.List;
+import java.util.SequencedCollection;
+import net.kyori.adventure.key.Key;
+import org.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Represents the post-effects that can be applied to a player.
+ * @see <a href="https://minecraft.wiki/w/Shader#Post-processing_effects">Post-Effects - Minecraft Wiki</a>
+ */
+@NullMarked
+public interface PlayerPostEffects {
+
+    /**
+     * Gets the list of post-effects that are currently applied to the player.
+     *
+     * @return an unmodifiable list of post-effects
+     */
+    @Unmodifiable
+    List<Key> values();
+
+    /**
+     * Sets the list of post-effects that are currently applied to the player.
+     *
+     * @param postEffects the list of post-effects to set
+     * @return true if the post-effects were changed, false if they were the same
+     */
+    boolean set(SequencedCollection<Key> postEffects);
+
+    /**
+     * Adds a post-effect to the player.
+     *
+     * @param effect the key post-effect to add
+     * @return true if the post-effect was added, false if it was already present
+     */
+    boolean add(Key effect);
+
+    /**
+     * Removes a post-effect from the player.
+     *
+     * @param effect the key post-effect to remove
+     * @return true if the post-effect was removed, false if it was not present
+     */
+    boolean remove(Key effect);
+
+    /**
+     * Clears all post-effects from the player.
+     *
+     * @return true if any post-effects were cleared, false if there were none
+     */
+    boolean clear();
+
+    /**
+     * Forces an immediate update of post-effects currently applied to the player.
+     * <p>
+     * Calling this method manually is usually unnecessary, as post-effects are automatically
+     * synchronized at the end of the player entity tick. It should only be called if changes
+     * need to be synchronized immediately.
+     */
+    void update();
+
+}

paper-api/src/main/java/io/papermc/paper/event/block/BellRevealRaiderEvent.java

@@ -1,5 +1,6 @@
 package io.papermc.paper.event.block;
 
+import org.bukkit.Warning;
 import org.bukkit.block.Block;
 import org.bukkit.entity.Raider;
 import org.bukkit.event.Cancellable;
@@ -14,6 +15,7 @@ import org.jetbrains.annotations.NotNull;
  * @deprecated use {@link org.bukkit.event.block.BellResonateEvent}
  */
 @Deprecated(since = "1.19.4")
+@Warning(propagate = false)
 public class BellRevealRaiderEvent extends BlockEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/io/papermc/paper/event/block/BellRingEvent.java

@@ -1,5 +1,6 @@
 package io.papermc.paper.event.block;
 
+import org.bukkit.Warning;
 import org.bukkit.block.Block;
 import org.bukkit.block.BlockFace;
 import org.bukkit.entity.Entity;
@@ -13,6 +14,7 @@ import org.jetbrains.annotations.Nullable;
  * @deprecated use {@link org.bukkit.event.block.BellRingEvent}
  */
 @Deprecated(since = "1.19.4")
+@Warning(propagate = false)
 public class BellRingEvent extends org.bukkit.event.block.BellRingEvent {
 
     @ApiStatus.Internal

paper-api/src/main/java/io/papermc/paper/event/entity/EntityCollideWithEntityEvent.java

@@ -1,12 +1,12 @@
 package io.papermc.paper.event.entity;
 
+import java.util.List;
 import org.bukkit.entity.Entity;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.ApiStatus;
-import org.jetbrains.annotations.NotNull;
-import java.util.List;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Fired when two entities collide with each other.
@@ -15,6 +15,7 @@ import java.util.List;
  * Note that even if cancelled, the client may still run its own collision unless
  * disabled via player teams.
  */
+@NullMarked
 public class EntityCollideWithEntityEvent extends Event implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
@@ -22,8 +23,8 @@ public class EntityCollideWithEntityEvent extends Event implements Cancellable {
     private final List<Entity> entities;
 
     @ApiStatus.Internal
-    public EntityCollideWithEntityEvent(@NotNull Entity entity1, @NotNull Entity entity2) {
-        entities = List.of(entity1, entity2);
+    public EntityCollideWithEntityEvent(final Entity entity1, final Entity entity2) {
+        this.entities = List.of(entity1, entity2);
     }
 
     /**
@@ -31,23 +32,22 @@ public class EntityCollideWithEntityEvent extends Event implements Cancellable {
      *
      * @return entities that are involved in this event
      */
-    public @NotNull List<Entity> getEntities() {
-        return entities;
+    public List<Entity> getEntities() {
+        return this.entities;
     }
 
     @Override
-    public @NotNull HandlerList getHandlers() {
+    public HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 
-    @NotNull
     public static HandlerList getHandlerList() {
         return HANDLER_LIST;
     }
 
     @Override
     public boolean isCancelled() {
-        return cancelled;
+        return this.cancelled;
     }
 
     @Override

paper-api/src/main/java/io/papermc/paper/event/entity/EntityPotentSulfurLaunchEvent.java

@@ -0,0 +1,69 @@
+package io.papermc.paper.event.entity;
+
+import org.bukkit.Location;
+import org.bukkit.block.Block;
+import org.bukkit.entity.Entity;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.entity.EntityEvent;
+import org.bukkit.util.Vector;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when an entity is launched upward by a Potent Sulfur geyser.
+ */
+@NullMarked
+public class EntityPotentSulfurLaunchEvent extends EntityEvent {
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final Block sulfurBlock;
+    private final Location sourceLocation;
+
+    private final Vector launchVelocity;
+
+    @ApiStatus.Internal
+    public EntityPotentSulfurLaunchEvent(
+        final Entity entity,
+        final Block sulfurBlock,
+        final Location sourceLocation,
+        final Vector launchVelocity
+    ) {
+        super(entity);
+        this.sulfurBlock = sulfurBlock;
+        this.sourceLocation = sourceLocation;
+        this.launchVelocity = launchVelocity;
+    }
+
+    /**
+     * Gets the Potent Sulfur block.
+     */
+    public Block getSulfurBlock() {
+        return this.sulfurBlock;
+    }
+
+    /**
+     * Gets the location where the geyser exits the water column.
+     */
+    public Location getSourceLocation() {
+        return this.sourceLocation.clone();
+    }
+
+    /**
+     * Gets the velocity that will be added to the entity.
+     * <br>
+     * This value is read-only, changes made to it <b>will not</b> have any
+     * effect on the final launch velocity.
+     */
+    public Vector getLaunchVelocity() {
+        return this.launchVelocity.clone();
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/entity/ItemTransportingEntitySortEvent.java

@@ -0,0 +1,99 @@
+package io.papermc.paper.event.entity;
+
+import org.bukkit.block.Container;
+import org.bukkit.entity.CopperGolem;
+import org.bukkit.entity.Entity;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.entity.EntityEvent;
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when an item-transporting entity (ex a {@link CopperGolem})
+ * is inspecting a destination {@link Container} to decide if the item it is holding
+ * belongs in said container.
+ * <br>
+ * This gives plugin developers an opportunity to
+ * override the {@link CopperGolem}'s sorting behavior.
+ * <br>
+ * <b>Note:</b> This event can be called twice during a single
+ * "interaction", once before the container is opened, and again before items are
+ * added and the container is closed.
+ */
+@NullMarked
+public class ItemTransportingEntitySortEvent extends EntityEvent {
+    protected static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final ItemStack itemStack;
+    private final Inventory containerInventory;
+    private Result result;
+
+    @ApiStatus.Internal
+    public ItemTransportingEntitySortEvent(
+        final Entity entity,
+        final ItemStack itemStack,
+        final Inventory containerInventory
+    ) {
+        super(entity);
+        this.containerInventory = containerInventory;
+        this.itemStack = itemStack;
+        this.result = Result.DEFAULT;
+    }
+
+    /**
+     * Sets the sorting decision for the held item and the inspected container.
+     * <ul>
+     *   <li>{@link Result#ALLOW}: the item belongs in the container.</li>
+     *   <li>{@link Result#DENY}: the item does not belong in the container.</li>
+     *   <li>{@link Result#DEFAULT}: use the vanilla sorting logic.</li>
+     * </ul>
+     *
+     * @param result the sorting decision
+     * @see Result
+     */
+    public void setResult(final Result result) {
+        this.result = result;
+    }
+
+    /**
+     * Gets the current sorting decision. Starts as {@link Result#DEFAULT}
+     * and may have been modified by other plugins.
+     *
+     * @return the current sorting decision
+     * @see #setResult(Result)
+     */
+    public Result getResult() {
+        return this.result;
+    }
+
+    /**
+     * Gets the inventory of the container the entity is comparing
+     * against the held item.
+     *
+     * @return the inventory of the potential destination container
+     */
+    public Inventory getContainerInventory() {
+        return this.containerInventory;
+    }
+
+    /**
+     * Clone of the ItemStack held by the entity that is being compared
+     * against the container.
+     *
+     * @return The held ItemStack
+     */
+    public ItemStack getItemStack() {
+        return this.itemStack.clone();
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/inventory/PlayerBundleItemSelectEvent.java

@@ -0,0 +1,199 @@
+package io.papermc.paper.event.inventory;
+
+import org.bukkit.entity.Player;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.inventory.InventoryClickEvent;
+import org.bukkit.event.inventory.InventoryEvent;
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.InventoryView;
+import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+import java.util.OptionalInt;
+
+/**
+ * Called when a {@link Player} selects an item inside a bundle.
+ *
+ * @apiNote This event does not fire for bundle item selections in creative mode player inventories.
+ */
+@NullMarked
+public final class PlayerBundleItemSelectEvent extends InventoryEvent {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final ItemStack bundle;
+    private final int rawSlot;
+    private final int slot;
+
+    private final ItemStack previousItem;
+    private final ItemStack selectedItem;
+
+    private final int previousIndex;
+    private final int selectedIndex;
+    private final Direction direction;
+
+    @ApiStatus.Internal
+    public PlayerBundleItemSelectEvent(final InventoryView view, final ItemStack bundle, final int rawSlot, final ItemStack previousItem, final ItemStack selectedItem, final int previousIndex, final int selectedIndex, final Direction direction) {
+        super(view);
+
+        this.bundle = bundle;
+        this.rawSlot = rawSlot;
+        this.slot = view.convertSlot(rawSlot);
+
+        this.previousItem = previousItem;
+        this.selectedItem = selectedItem;
+
+        this.previousIndex = previousIndex;
+        this.selectedIndex = selectedIndex;
+        this.direction = direction;
+    }
+
+    /**
+     * Gets the player who triggered the event.
+     *
+     * @return the player
+     */
+    public Player getPlayer() {
+        return (Player) this.getView().getPlayer();
+    }
+
+    /**
+     * Gets the bundle item.
+     *
+     * @return the bundle item
+     */
+    public ItemStack getBundle() {
+        return this.bundle;
+    }
+
+    /**
+     * Gets the slot number of the bundle, depending on which {@link Inventory} it is located in.
+     *
+     * @return the slot number
+     * @see InventoryClickEvent#getSlot()
+     */
+    public int getSlot() {
+        return this.slot;
+    }
+
+    /**
+     * Gets the raw slot number of the bundle inside the {@link InventoryView}.
+     *
+     * @return the raw slot number
+     * @see InventoryClickEvent#getRawSlot()
+     */
+    public int getRawSlot() {
+        return this.rawSlot;
+    }
+
+    /**
+     * Gets the previously selected item inside the bundle. If no item was previously selected, this will return an empty item.
+     *
+     * @return the previously selected item
+     */
+    public ItemStack getPreviousItem() {
+        return this.previousItem.clone();
+    }
+
+    /**
+     * Gets the selected item inside the bundle.
+     *
+     * @return the selected item
+     */
+    public ItemStack getSelectedItem() {
+        return this.selectedItem.clone();
+    }
+
+    /**
+     * Gets the previously selected index. If no item was previously selected, this will be -1.
+     *
+     * @return the previously selected index
+     */
+    public int getPreviousIndex() {
+        return this.previousIndex;
+    }
+
+    /**
+     * Gets the selected index.
+     *
+     * @return the selected index
+     */
+    public int getSelectedIndex() {
+        return this.selectedIndex;
+    }
+
+    /**
+     * Gets the direction from the previous selection to the new one.
+     *
+     * @apiNote The direction cannot be reliably determined if there are less than three item stacks inside the bundle, in which case this returns {@link Direction#UNKNOWN}.
+     *
+     * @return the direction
+     */
+    public Direction getDirection() {
+        return this.direction;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+
+    /**
+     * Represents a selection direction.
+     */
+    public enum Direction {
+        /**
+         * Represents forward direction.
+         */
+        FORWARD(OptionalInt.of(1)),
+        /**
+         * Represents backward direction.
+         */
+        BACKWARD(OptionalInt.of(-1)),
+        /**
+         * Represents indeterminable direction.
+         * <p>
+         * That is, for bundles with less than three item stacks inside.
+         */
+        UNKNOWN(OptionalInt.empty());
+
+        private final OptionalInt delta;
+
+        Direction(final OptionalInt delta) {
+            this.delta = delta;
+        }
+
+        /**
+         * Returns the delta integer of the direction.
+         * <p>
+         * Directions are mapped the following:
+         * <ul>
+         *     <li>{@link #FORWARD} to {@code +1}</li>
+         *     <li>{@link #BACKWARD} to {@code -1}</li>
+         *     <li>{@link #UNKNOWN} to {@link OptionalInt#empty()}</li>
+         * </ul>
+         *
+         * @return the delta
+         */
+        public OptionalInt getDelta() {
+            return this.delta;
+        }
+
+        /**
+         * Returns the direction opposite to this direction.
+         *
+         * @return the flipped direction or {@link #UNKNOWN} if the direction is unknown
+         */
+        public Direction flip() {
+            return switch (this) {
+                case FORWARD -> BACKWARD;
+                case BACKWARD -> FORWARD;
+                case UNKNOWN -> UNKNOWN;
+            };
+        }
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/inventory/PrepareHopperTransferEvent.java

@@ -0,0 +1,97 @@
+package io.papermc.paper.event.inventory;
+
+import com.google.common.base.Preconditions;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.inventory.InventoryMoveItemEvent;
+import org.bukkit.inventory.Inventory;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when a hopper or hopper minecart is about to choose an item to move,
+ * before any {@link InventoryMoveItemEvent}.
+ * <p>
+ * The hopper treats disallowed slots of the source as if they do not exist, so
+ * a source with items only in disallowed slots is treated as empty.
+ */
+@NullMarked
+public class PrepareHopperTransferEvent extends Event {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final Inventory source;
+    private final Inventory destination;
+    private final boolean didSourceInitiate;
+    protected long disallowedSlots;
+
+    @ApiStatus.Internal
+    public PrepareHopperTransferEvent(final Inventory source, final Inventory destination, final boolean didSourceInitiate) {
+        this.source = source;
+        this.destination = destination;
+        this.didSourceInitiate = didSourceInitiate;
+    }
+
+    /**
+     * Gets the Inventory that items are being taken from
+     *
+     * @return Inventory that items are being taken from
+     */
+    public Inventory getSource() {
+        return this.source;
+    }
+
+    /**
+     * Gets the Inventory that items are being put into
+     *
+     * @return Inventory that items are being put into
+     */
+    public Inventory getDestination() {
+        return this.destination;
+    }
+
+    /**
+     * Gets the Inventory that initiated the transfer. This will always be
+     * either the destination or source Inventory.
+     *
+     * @return Inventory that initiated the transfer
+     */
+    public Inventory getInitiator() {
+        return this.didSourceInitiate ? this.source : this.destination;
+    }
+
+    /**
+     * Gets if the hopper is allowed to take items from a slot of {@link #getSource()}.
+     *
+     * @param slot the slot
+     * @return true if the slot is allowed
+     */
+    public boolean isSlotAllowed(final int slot) {
+        Preconditions.checkArgument(slot >= 0 && slot < this.source.getSize(), "Slot %s is outside the source inventory", slot);
+        return (this.disallowedSlots & (1L << slot)) == 0;
+    }
+
+    /**
+     * Sets if the hopper is allowed to take items from a slot of {@link #getSource()}.
+     *
+     * @param slot the slot
+     * @param allowed whether the slot is allowed
+     */
+    public void setSlotAllowed(final int slot, final boolean allowed) {
+        Preconditions.checkArgument(slot >= 0 && slot < this.source.getSize(), "Slot %s is outside the source inventory", slot);
+        if (allowed) {
+            this.disallowedSlots &= ~(1L << slot);
+        } else {
+            this.disallowedSlots |= 1L << slot;
+        }
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/player/ChatEvent.java

@@ -18,7 +18,7 @@ import org.jspecify.annotations.NullMarked;
  * It is recommended to use {@link AsyncChatEvent} instead, wherever possible.
  */
 @Deprecated
-@Warning(reason = "Listening to this event forces chat to wait for the main thread, delaying chat messages.")
+@Warning(reason = "Listening to this event forces chat to wait for the main thread, delaying chat messages.", propagate = false)
 @NullMarked
 public final class ChatEvent extends AbstractChatEvent {
 

paper-api/src/main/java/io/papermc/paper/event/player/PlayerTrackEntityEvent.java

@@ -15,6 +15,8 @@ import org.jspecify.annotations.NullMarked;
  * <p>
  * Adding or removing entities from the world at the point in time this event is called is completely
  * unsupported and should be avoided.
+ * Teleporting entities in the world at the point in time this event is called yields an undefined tracker
+ * behavior and should be avoided.
  */
 @NullMarked
 public class PlayerTrackEntityEvent extends PlayerEvent implements Cancellable {

paper-api/src/main/java/io/papermc/paper/event/player/PlayerUntrackEntityEvent.java

@@ -12,6 +12,8 @@ import org.jspecify.annotations.NullMarked;
  * <p>
  * Adding or removing entities from the world at the point in time this event is called is completely
  * unsupported and should be avoided.
+ * Teleporting entities in the world at the point in time this event is called yields an undefined tracker
+ * behavior and should be avoided.
  */
 @NullMarked
 public class PlayerUntrackEntityEvent extends PlayerEvent {

paper-api/src/main/java/io/papermc/paper/persistence/PersistentDataContainerView.java

@@ -1,6 +1,7 @@
 package io.papermc.paper.persistence;
 
 import java.util.Set;
+import com.google.common.base.Preconditions;
 import org.bukkit.NamespacedKey;
 import org.bukkit.persistence.PersistentDataAdapterContext;
 import org.bukkit.persistence.PersistentDataContainer;
@@ -66,6 +67,32 @@ public interface PersistentDataContainerView {
      */
     boolean has(NamespacedKey key);
 
+    /**
+     * Returns if the persistent metadata provider has metadata registered
+     * matching the provided parameters.
+     * <p>
+     * This method will only return true if the found value has the same primitive
+     * data type as the provided data key.
+     * <p>
+     * Storing a value using a custom {@link PersistentDataType} implementation
+     * will not store the complex data type. Therefore, storing a UUID (by
+     * storing a byte[]) will match has("key", {@link PersistentDataType#BYTE_ARRAY}).
+     * Likewise, a stored byte[] will always match your UUID {@link PersistentDataType}
+     * even if it is not 16 bytes long.
+     * <p>
+     * This method is only usable for custom object keys. Overwriting existing
+     * tags, like the display name, will not work as the values are stored
+     * using your namespace.
+     *
+     * @param dataKey the data key the value is stored under
+     * @return if a value with the provided key and type exists
+     * @throws IllegalArgumentException if the key to look up is null
+     */
+    default boolean has(final PersistentDataKey<?> dataKey) {
+        Preconditions.checkArgument(dataKey != null, "The data key cannot be null");
+        return this.has(dataKey.key(), dataKey.dataType());
+    }
+
     /**
      * Returns the metadata value that is stored on the
      * {@link PersistentDataHolder} instance.
@@ -110,6 +137,46 @@ public interface PersistentDataContainerView {
      */
     <P, C> C getOrDefault(NamespacedKey key, PersistentDataType<P, C> type, C defaultValue);
 
+    /**
+     * Returns the metadata value that is stored on the
+     * {@link PersistentDataHolder} instance.
+     *
+     * @param dataKey the data key to look up in the custom tag map
+     * @param <C> the generic type of the eventually created complex object
+     * @return the value or {@code null} if no value was mapped under the given
+     * value
+     * @throws IllegalArgumentException if the data key to look up is null
+     * @throws IllegalArgumentException if a value exists under the given key,
+     * but cannot be accessed using the given type
+     * @throws IllegalArgumentException if no suitable adapter was found for
+     * the {@link PersistentDataType#getPrimitiveType()}
+     */
+    default <C> @Nullable C get(final PersistentDataKey<C> dataKey) {
+        Preconditions.checkArgument(dataKey != null, "The data key cannot be null");
+        return this.get(dataKey.key(), dataKey.dataType());
+    }
+
+    /**
+     * Returns the metadata value that is stored on the
+     * {@link PersistentDataHolder} instance. If the value does not exist in the
+     * container, the default value provided is returned.
+     *
+     * @param dataKey the data key to look up in the custom tag map
+     * @param defaultValue the default value to return if no value was found for
+     * the provided key
+     * @param <C> the generic type of the eventually created complex object
+     * @return the value or the default value if no value was mapped under the given key
+     * @throws IllegalArgumentException if the data key to look up is null
+     * @throws IllegalArgumentException if a value exists under the given key,
+     * but cannot be accessed using the given type
+     * @throws IllegalArgumentException if no suitable adapter was found for
+     * the {@link PersistentDataType#getPrimitiveType()}
+     */
+    default <C> C getOrDefault(final PersistentDataKey<C> dataKey, final C defaultValue) {
+        Preconditions.checkArgument(dataKey != null, "The data key cannot be null");
+        return this.getOrDefault(dataKey.key(), dataKey.dataType(), defaultValue);
+    }
+
     /**
      * Get the set of keys present on this {@link PersistentDataContainer}
      * instance.

paper-api/src/main/java/io/papermc/paper/persistence/PersistentDataKey.java

@@ -0,0 +1,69 @@
+package io.papermc.paper.persistence;
+
+import io.papermc.paper.InternalAPIBridge;
+import net.kyori.adventure.key.Key;
+import org.bukkit.NamespacedKey;
+import org.bukkit.persistence.PersistentDataContainer;
+import org.bukkit.persistence.PersistentDataType;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * This class represents the union of a {@link Key} and a
+ * {@link PersistentDataType}.
+ * <p>
+ * The advantage of this class is more direct, typed access to data stored in a {@link PersistentDataContainer}.
+ * Instead of having to keep track of the {@link NamespacedKey} and {@link PersistentDataType} separately
+ * when working with PDC, this class allows you to store both together.
+ * <p>
+ * <h2>Example usage</h2>
+ * <pre>{@code
+ * public class CustomLogic {
+ *   public static final PersistentDataKey<Integer> TRACKED_VALUE = PersistentDataKey.of(
+ *     Key.key("custom:tracked_value"),
+ *     PersistentDataType.INTEGER
+ *   );
+ *   public static final PersistentDataKey<UUID> OWNING_PLAYER = PersistentDataKey.of(
+ *     Key.key("custom:owning_player"),
+ *     new UUIDTagType() // Custom type
+ *   );
+ *
+ *   // Checks if the stored PDC value for OWNING_PLAYER matches the executor UUID and adds
+ *   // 1 to the TRACKED_VALUE, if it does.
+ *   public static void incrementIfOwner(PersistentDataContainer pdc, UUID executor) {
+ *     if (!Objects.equals(pdc.get(OWNING_PLAYER), executor) {
+ *       return;
+ *     }
+ *
+ *     pdc.set(TRACKED_VALUE, pdc.getOrDefault(TRACKED_VALUE, 0) + 1);
+ *   }
+ * }
+ * }</pre>
+ *
+ * @param <C> the retrieved object type when applying this tag type
+ */
+@NullMarked
+public interface PersistentDataKey<C> {
+
+    /**
+     * Creates a new {@link PersistentDataKey} with the given {@link Key} and {@link PersistentDataType}.
+     *
+     * @param key  the access key to store
+     * @param type the persistent data type to reference
+     * @param <C>  the retrieved object type when applying this tag type
+     * @return a new {@link PersistentDataKey} of the given key and type
+     * @throws IllegalArgumentException if either key or type are null
+     */
+    static <C> PersistentDataKey<C> of(final Key key, final PersistentDataType<?, C> type) {
+        return InternalAPIBridge.get().createPersistentDataKey(key, type);
+    }
+
+    /**
+     * {@return the access key of this {@link PersistentDataKey}}
+     */
+    NamespacedKey key();
+
+    /**
+     * {@return the data type of this {@link PersistentDataKey}}
+     */
+    PersistentDataType<?, C> dataType();
+}

paper-api/src/main/java/io/papermc/paper/registry/RegistryKey.java

@@ -5,6 +5,8 @@ import io.papermc.paper.datacomponent.DataComponentType;
 import io.papermc.paper.dialog.Dialog;
 import io.papermc.paper.entity.poi.PoiType;
 import io.papermc.paper.registry.tag.TagKey;
+import io.papermc.paper.world.Timeline;
+import io.papermc.paper.world.WorldClock;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.key.KeyPattern;
 import net.kyori.adventure.key.Keyed;
@@ -42,6 +44,7 @@ import org.bukkit.inventory.meta.trim.TrimPattern;
 import org.bukkit.map.MapCursor;
 import org.bukkit.potion.PotionEffectType;
 import org.bukkit.potion.PotionType;
+import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 import static io.papermc.paper.registry.RegistryKeyImpl.create;
@@ -269,6 +272,16 @@ public sealed interface RegistryKey<T> extends Keyed permits RegistryKeyImpl {
      * @see io.papermc.paper.registry.keys.DialogKeys
      */
     RegistryKey<Dialog> DIALOG = create("dialog");
+    /**
+     * Data-driven registry for world clocks.
+     * @see io.papermc.paper.registry.keys.WorldClockKeys
+     */
+    RegistryKey<WorldClock> WORLD_CLOCK = create("world_clock");
+    /**
+     * Data-driven registry for timelines.
+     * @see io.papermc.paper.registry.keys.TimelineKeys
+     */
+    RegistryKey<Timeline> TIMELINE = create("timeline");
 
 
     /* ******************* *

paper-api/src/main/java/io/papermc/paper/registry/data/TimelineRegistryEntry.java

@@ -0,0 +1,132 @@
+package io.papermc.paper.registry.data;
+
+import io.papermc.paper.registry.RegistryBuilder;
+import io.papermc.paper.registry.TypedKey;
+import io.papermc.paper.world.Timeline;
+import io.papermc.paper.world.WorldClock;
+import java.util.Map;
+import java.util.OptionalInt;
+import net.kyori.adventure.key.Key;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Range;
+
+import static io.papermc.paper.util.BoundChecker.requireNonNegative;
+
+/**
+ * A data-centric version-specific registry entry for the {@link Timeline} type.
+ */
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface TimelineRegistryEntry {
+
+    /**
+     * Gets the clock that drives this timeline.
+     *
+     * @return the clock
+     */
+    @Contract(pure = true)
+    TypedKey<WorldClock> clock();
+
+    /**
+     * Gets the timeline period, if any.
+     *
+     * @return the timeline period
+     */
+    @Contract(pure = true)
+    OptionalInt periodTicks();
+
+    /**
+     * Gets the time markers defined by this timeline.
+     *
+     * @return the time markers
+     */
+    @Contract(pure = true)
+    Map<Key, TimeMarker> timeMarkers();
+
+    /**
+     * A mutable builder for the {@link TimelineRegistryEntry} plugins may change in applicable registry events.
+     * <p>
+     * The following values are required for each builder:
+     * <ul>
+     *     <li>{@link #clock(TypedKey)}</li>
+     * </ul>
+     */
+    @ApiStatus.NonExtendable
+    interface Builder extends TimelineRegistryEntry, RegistryBuilder<Timeline> {
+
+        /**
+         * Sets the clock that drives this timeline.
+         *
+         * @param clock the clock
+         * @return this builder
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder clock(TypedKey<WorldClock> clock);
+
+        /**
+         * Sets the timeline period.
+         *
+         * @param periodTicks the period in ticks
+         * @return this builder
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder periodTicks(@Range(from = 1, to = Integer.MAX_VALUE) int periodTicks);
+
+        /**
+         * Clears the timeline period.
+         *
+         * @return this builder
+         */
+        @Contract(value = "-> this", mutates = "this")
+        Builder clearPeriodTicks();
+
+        /**
+         * Adds or replaces a time marker on this timeline.
+         *
+         * @param key            the time marker key
+         * @param ticks          the marker tick
+         * @param showInCommands whether the marker should be suggested in commands
+         * @return this builder
+         */
+        @Contract(value = "_, _, _ -> this", mutates = "this")
+        Builder addTimeMarker(Key key, @Range(from = 0, to = Integer.MAX_VALUE) int ticks, boolean showInCommands);
+    }
+
+    /**
+     * A time marker defined by a timeline.
+     */
+    @ApiStatus.NonExtendable
+    interface TimeMarker {
+
+        /**
+         * Gets the tick this marker occurs on.
+         *
+         * @return the marker tick
+         */
+        @Range(from = 0, to = Integer.MAX_VALUE)
+        int ticks();
+
+        /**
+         * Gets whether this marker should be suggested in commands.
+         *
+         * @return whether the marker should be suggested in commands
+         */
+        boolean showInCommands();
+
+        /**
+         * Creates a new time marker instance based on the passed values.
+         *
+         * @param ticks          the tick this marker occurs on, as returned by {@link #ticks()}
+         * @param showInCommands whether the marker should be suggested in commands, as returned by {@link #showInCommands()}
+         * @return the created instance
+         */
+        @Contract(value = "_, _ -> new", pure = true)
+        static TimeMarker of(@Range(from = 0, to = Integer.MAX_VALUE) final int ticks, final boolean showInCommands) {
+            record Impl(int ticks, boolean showInCommands) implements TimeMarker {
+            }
+
+            return new Impl(requireNonNegative(ticks, "ticks"), showInCommands);
+        }
+    }
+}

paper-api/src/main/java/io/papermc/paper/registry/data/WorldClockRegistryEntry.java

@@ -0,0 +1,19 @@
+package io.papermc.paper.registry.data;
+
+import io.papermc.paper.registry.RegistryBuilder;
+import io.papermc.paper.world.WorldClock;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * A data-centric version-specific registry entry for the {@link WorldClock} type.
+ */
+@ApiStatus.NonExtendable
+public interface WorldClockRegistryEntry {
+
+    /**
+     * A mutable builder for the {@link WorldClockRegistryEntry} plugins may change in applicable registry events.
+     */
+    @ApiStatus.NonExtendable
+    interface Builder extends WorldClockRegistryEntry, RegistryBuilder<WorldClock> {
+    }
+}

paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEvents.java

@@ -17,11 +17,15 @@ import io.papermc.paper.registry.data.JukeboxSongRegistryEntry;
 import io.papermc.paper.registry.data.PaintingVariantRegistryEntry;
 import io.papermc.paper.registry.data.PigVariantRegistryEntry;
 import io.papermc.paper.registry.data.SulfurCubeArchetypeRegistryEntry;
+import io.papermc.paper.registry.data.TimelineRegistryEntry;
 import io.papermc.paper.registry.data.TrimMaterialRegistryEntry;
 import io.papermc.paper.registry.data.TrimPatternRegistryEntry;
 import io.papermc.paper.registry.data.WolfVariantRegistryEntry;
+import io.papermc.paper.registry.data.WorldClockRegistryEntry;
 import io.papermc.paper.registry.data.ZombieNautilusVariantRegistryEntry;
 import io.papermc.paper.registry.data.dialog.DialogRegistryEntry;
+import io.papermc.paper.world.Timeline;
+import io.papermc.paper.world.WorldClock;
 import org.bukkit.Art;
 import org.bukkit.GameEvent;
 import org.bukkit.JukeboxSong;
@@ -68,6 +72,8 @@ public final class RegistryEvents {
     public static final RegistryEventProvider<ZombieNautilus.Variant, ZombieNautilusVariantRegistryEntry.Builder> ZOMBIE_NAUTILUS_VARIANT = create(RegistryKey.ZOMBIE_NAUTILUS_VARIANT);
     public static final RegistryEventProvider<SulfurCube.Archetype, SulfurCubeArchetypeRegistryEntry.Builder> SULFUR_CUBE_ARCHETYPE = create(RegistryKey.SULFUR_CUBE_ARCHETYPE);
     public static final RegistryEventProvider<Dialog, DialogRegistryEntry.Builder> DIALOG = create(RegistryKey.DIALOG);
+    public static final RegistryEventProvider<WorldClock, WorldClockRegistryEntry.Builder> WORLD_CLOCK = create(RegistryKey.WORLD_CLOCK);
+    public static final RegistryEventProvider<Timeline, TimelineRegistryEntry.Builder> TIMELINE = create(RegistryKey.TIMELINE);
     // End generate - RegistryEvents
 
     private RegistryEvents() {

paper-api/src/main/java/io/papermc/paper/world/Timeline.java

@@ -0,0 +1,31 @@
+package io.papermc.paper.world;
+
+import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryKey;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
+import org.bukkit.Keyed;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Represents a timeline that can apply environment attributes or define time markers for a {@link WorldClock}.
+ */
+@NullMarked
+@ApiStatus.NonExtendable
+public interface Timeline extends Keyed {
+
+    // Start generate - Timeline
+    Timeline DAY = getTimeline("day");
+
+    Timeline EARLY_GAME = getTimeline("early_game");
+
+    Timeline MOON = getTimeline("moon");
+
+    Timeline VILLAGER_SCHEDULE = getTimeline("villager_schedule");
+    // End generate - Timeline
+
+    private static Timeline getTimeline(@KeyPattern.Value final String key) {
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.TIMELINE).getOrThrow(Key.key(Key.MINECRAFT_NAMESPACE, key));
+    }
+}

paper-api/src/main/java/io/papermc/paper/world/WorldClock.java

@@ -0,0 +1,27 @@
+package io.papermc.paper.world;
+
+import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryKey;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
+import org.bukkit.Keyed;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Represents a world clock that tracks time for worlds and drives timelines.
+ */
+@NullMarked
+@ApiStatus.NonExtendable
+public interface WorldClock extends Keyed {
+
+    // Start generate - WorldClock
+    WorldClock OVERWORLD = getWorldClock("overworld");
+
+    WorldClock THE_END = getWorldClock("the_end");
+    // End generate - WorldClock
+
+    private static WorldClock getWorldClock(@KeyPattern.Value final String key) {
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.WORLD_CLOCK).getOrThrow(Key.key(Key.MINECRAFT_NAMESPACE, key));
+    }
+}

paper-api/src/main/java/io/papermc/paper/world/chunk/ChunkGenerationState.java

@@ -0,0 +1,35 @@
+package io.papermc.paper.world.chunk;
+
+import org.bukkit.World;
+
+/**
+ * The generation state of a chunk, as reported by {@link World#getChunkGenerationState(int, int)}
+ * and {@link World#getChunkGenerationStateAsync(int, int)}.
+ */
+public enum ChunkGenerationState {
+    /**
+     * The chunk is not loaded and has no saved data.
+     */
+    NOT_GENERATED,
+    /**
+     * Generation of the chunk has started but has not completed. Loading the chunk
+     * will complete generation.
+     */
+    PARTIAL,
+    /**
+     * The chunk has saved data that must be upgraded before it can be loaded, for
+     * example because it was saved by an older version, or it has pending world
+     * generation from a world height change. Loading the chunk will modify it.
+     *
+     * <p>
+     * The chunk may be partially or fully generated; generation progress is not
+     * determined for chunks in this state, as doing so would require upgrading
+     * the chunk data.
+     * </p>
+     */
+    OUTDATED,
+    /**
+     * The chunk is fully generated and up to date. Loading it will not change it.
+     */
+    GENERATED
+}

paper-api/src/main/java/io/papermc/paper/world/chunk/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Package for Chunk types.
+ */
+@NullMarked
+package io.papermc.paper.world.chunk;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/org/bukkit/Bukkit.java

@@ -961,8 +961,7 @@ public final class Bukkit {
      * Create a new explorer map targeting the closest nearby structure of a
      * given {@link StructureType}.
      * <br>
-     * This method uses implementation default values for radius and
-     * findUnexplored (usually 100, true).
+     * This method uses a radius of 100 and only searches for unexplored structures.
      *
      * @param world the world the map will belong to
      * @param location the origin location to find the nearest structure
@@ -986,8 +985,7 @@ public final class Bukkit {
      * Create a new explorer map targeting the closest nearby structure of a
      * given {@link org.bukkit.generator.structure.StructureType}.
      * <br>
-     * This method uses implementation default values for radius and
-     * findUnexplored (usually 100, true).
+     * This method uses a radius of 100 and only searches for unexplored structures.
      *
      * @param world the world the map will belong to
      * @param location the origin location to find the nearest structure
@@ -1021,6 +1019,45 @@ public final class Bukkit {
     public static @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull org.bukkit.generator.structure.StructureType structureType, @NotNull org.bukkit.map.MapCursor.Type mapIcon, int radius, boolean findUnexplored) {
         return server.createExplorerMap(world, location, structureType, mapIcon, radius, findUnexplored);
     }
+
+    /**
+     * Create a new explorer map targeting the closest nearby specific
+     * {@link org.bukkit.generator.structure.Structure}.
+     * <br>
+     * This method uses a radius of 100 and only searches for unexplored structures.
+     *
+     * @param world the world the map will belong to
+     * @param location the origin location to find the nearest structure
+     * @param structure the specific structure to find
+     * @param mapIcon the map icon to use on the map
+     * @return a newly created item stack or null if it can't find a location
+     *
+     * @see World#locateNearestStructure(org.bukkit.Location,
+     *      org.bukkit.generator.structure.Structure, int, boolean)
+     */
+    public static @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull org.bukkit.generator.structure.Structure structure, @NotNull org.bukkit.map.MapCursor.Type mapIcon) {
+        return server.createExplorerMap(world, location, structure, mapIcon);
+    }
+
+    /**
+     * Create a new explorer map targeting the closest nearby specific
+     * {@link org.bukkit.generator.structure.Structure}.
+     *
+     * @param world the world the map will belong to
+     * @param location the origin location to find the nearest structure
+     * @param structure the specific structure to find
+     * @param mapIcon the map icon to use on the map
+     * @param radius radius to search, see World#locateNearestStructure for more
+     *               information
+     * @param findUnexplored whether to find unexplored structures
+     * @return the newly created item stack or null if it can't find a location
+     *
+     * @see World#locateNearestStructure(org.bukkit.Location,
+     *      org.bukkit.generator.structure.Structure, int, boolean)
+     */
+    public static @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull org.bukkit.generator.structure.Structure structure, @NotNull org.bukkit.map.MapCursor.Type mapIcon, int radius, boolean findUnexplored) {
+        return server.createExplorerMap(world, location, structure, mapIcon, radius, findUnexplored);
+    }
     // Paper end
 
     /**
@@ -1079,7 +1116,11 @@ public final class Bukkit {
      *
      * @param name the name of the command to retrieve
      * @return a plugin command if found, null otherwise
+     * @apiNote plugin developers should prefer to use the
+     *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+     *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended.
      */
+    @ApiStatus.Obsolete(since = "26.3")
     @Nullable
     public static PluginCommand getPluginCommand(@NotNull String name) {
         return server.getPluginCommand(name);
@@ -1108,14 +1149,14 @@ public final class Bukkit {
 
     /**
      * Adds a recipe to the crafting manager.
-     * Recipes added with this method won't be sent to the client automatically.
+     * Recipes added with this method will be sent to the client automatically.
      * <p>
      * Players still have to discover recipes via {@link Player#discoverRecipe(NamespacedKey)}
      * before seeing them in their recipe book.
      *
      * @param recipe the recipe to add
      * @return true if the recipe was added, false if it wasn't for some reason
-     * @see #addRecipe(Recipe, boolean)
+     * @throws IllegalStateException if the recipe is already added to the crafting manager
      */
     @Contract("null -> false")
     public static boolean addRecipe(@Nullable Recipe recipe) {
@@ -1125,14 +1166,30 @@ public final class Bukkit {
     /**
      * Adds a recipe to the crafting manager.
      *
-     * @apiNote resendRecipes is ignored at the moment for stability reasons, recipes will always be updated
      * @param recipe the recipe to add
-     * @param resendRecipes true to update the client with the full set of recipes
+     * @param resendRecipes ignored, refer to the deprecation note
      * @return true if the recipe was added, false if it wasn't for some reason
+     * @throws IllegalStateException if the recipe is already added to the crafting manager
+     * @deprecated use {@link #addRecipe(Recipe)} instead, as Minecraft always resends recipes on a recipe added
      */
+    @Deprecated(since = "26.3")
     @Contract("null, _ -> false")
     public static boolean addRecipe(@Nullable Recipe recipe, boolean resendRecipes) {
-        return server.addRecipe(recipe, resendRecipes);
+        return server.addRecipe(recipe);
+    }
+
+    /**
+     * Adds multiple recipes to the crafting manager at once, resending recipes only once
+     * after all have been added.
+     *
+     * @apiNote This method differs from {@link #addRecipe} in that it will only resend the recipe book once instead of once per every recipe added
+     * @param recipes the recipes to add
+     * @return true if any recipe was added, false if none were for some reason
+     * @throws IllegalStateException if any of the recipes are already added to the crafting manager
+     * @see #addRecipe
+     */
+    public static boolean addRecipes(@NotNull Iterable<Recipe> recipes) {
+        return server.addRecipes(recipes);
     }
 
     /**
@@ -1313,8 +1370,18 @@ public final class Bukkit {
     }
 
     /**
-     * Remove a recipe from the server.
+     * Checks if the server has a recipe
      *
+     * @param key NamespacedKey of recipe to check for
+     * @return True if there is a recipe with a matching key
+     */
+    public static boolean hasRecipe(@NotNull NamespacedKey key) {
+        return server.hasRecipe(key);
+    }
+
+    /**
+     * Remove a recipe from the server.
+     * <br>
      * <b>Note that removing a recipe may cause permanent loss of data
      * associated with that recipe (eg whether it has been discovered by
      * players).</b>
@@ -1326,7 +1393,6 @@ public final class Bukkit {
         return server.removeRecipe(key);
     }
 
-    // Paper start - method to resend recipes
     /**
      * Remove a recipe from the server.
      * <p>
@@ -1335,14 +1401,26 @@ public final class Bukkit {
      * players).</b>
      *
      * @param key NamespacedKey of recipe to remove.
-     * @param resendRecipes true to update all clients on the new recipe list.
-     *                      Will only update if a recipe was actually removed
+     * @param resendRecipes ignored, refer to the deprecation note
      * @return True if recipe was removed
+     * @deprecated use {@link #removeRecipe(NamespacedKey)} instead, as Minecraft always resends recipes on recipe removal
      */
+    @Deprecated(since = "26.3")
     public static boolean removeRecipe(@NotNull NamespacedKey key, boolean resendRecipes) {
-        return server.removeRecipe(key, resendRecipes);
+        return server.removeRecipe(key);
+    }
+
+    /**
+     * Remove multiple recipes from the server.
+     *
+     * @apiNote This method differs from {@link #removeRecipe} in that it will only resend the recipe book once instead of once per every recipe removed
+     * @param keys the NamespacedKeys of the recipes to remove
+     * @return true if any recipe was removed, false if none were for some reason
+     * @see #removeRecipe
+     */
+    public static boolean removeRecipes(@NotNull Iterable<NamespacedKey> keys) {
+        return server.removeRecipes(keys);
     }
-    // Paper end - method to resend recipes
 
     /**
      * Gets a list of command aliases defined in the server properties.
@@ -2654,7 +2732,11 @@ public final class Bukkit {
      * Gets the active {@link org.bukkit.command.CommandMap}
      *
      * @return the active command map
+     * @apiNote plugin developers should prefer to use the
+     *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+     *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
      */
+    @ApiStatus.Obsolete(since = "26.3")
     @NotNull
     public static org.bukkit.command.CommandMap getCommandMap() {
         return server.getCommandMap();

paper-api/src/main/java/org/bukkit/Color.java

@@ -6,10 +6,12 @@ import java.util.Arrays;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Objects;
+import net.kyori.adventure.util.ARGBLike;
 import org.bukkit.configuration.serialization.ConfigurationSerializable;
 import org.bukkit.configuration.serialization.SerializableAs;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Range;
 
 /**
  * A container for a color palette. This class is immutable; the set methods
@@ -17,7 +19,7 @@ import org.jetbrains.annotations.Nullable;
  * but subject to change.
  */
 @SerializableAs("Color")
-public final class Color implements ConfigurationSerializable {
+public final class Color implements ConfigurationSerializable, ARGBLike {
     private static final int BIT_MASK = 0xff;
     private static final int DEFAULT_ALPHA = 255;
 
@@ -122,7 +124,12 @@ public final class Color implements ConfigurationSerializable {
      * @throws IllegalArgumentException if any value is strictly {@literal >255 or <0}
      */
     @NotNull
-    public static Color fromARGB(int alpha, int red, int green, int blue) throws IllegalArgumentException {
+    public static Color fromARGB(
+        final @Range(from = 0, to = 255) int alpha,
+        final @Range(from = 0, to = 255) int red,
+        final @Range(from = 0, to = 255) int green,
+        final @Range(from = 0, to = 255) int blue
+    ) throws IllegalArgumentException {
         return new Color(alpha, red, green, blue);
     }
 
@@ -136,7 +143,11 @@ public final class Color implements ConfigurationSerializable {
      * @throws IllegalArgumentException if any value is strictly {@literal >255 or <0}
      */
     @NotNull
-    public static Color fromRGB(int red, int green, int blue) throws IllegalArgumentException {
+    public static Color fromRGB(
+        final @Range(from = 0, to = 255) int red,
+        final @Range(from = 0, to = 255) int green,
+        final @Range(from = 0, to = 255) int blue
+    ) throws IllegalArgumentException {
         return new Color(DEFAULT_ALPHA, red, green, blue);
     }
 
@@ -150,7 +161,11 @@ public final class Color implements ConfigurationSerializable {
      * @throws IllegalArgumentException if any value is strictly {@literal >255 or <0}
      */
     @NotNull
-    public static Color fromBGR(int blue, int green, int red) throws IllegalArgumentException {
+    public static Color fromBGR(
+        final @Range(from = 0, to = 255) int blue,
+        final @Range(from = 0, to = 255) int green,
+        final @Range(from = 0, to = 255) int red
+    ) throws IllegalArgumentException {
         return new Color(DEFAULT_ALPHA, red, green, blue);
     }
 
@@ -164,7 +179,7 @@ public final class Color implements ConfigurationSerializable {
      *     bits
      */
     @NotNull
-    public static Color fromRGB(int rgb) throws IllegalArgumentException {
+    public static Color fromRGB(final int rgb) throws IllegalArgumentException {
         Preconditions.checkArgument((rgb >> 24) == 0, "Extraneous data in: %s", rgb);
         return fromRGB(rgb >> 16 & BIT_MASK, rgb >> 8 & BIT_MASK, rgb & BIT_MASK);
     }
@@ -177,7 +192,7 @@ public final class Color implements ConfigurationSerializable {
      * @return a new color object for specified values
      */
     @NotNull
-    public static Color fromARGB(int argb) {
+    public static Color fromARGB(final int argb) {
         return fromARGB(argb >> 24 & BIT_MASK, argb >> 16 & BIT_MASK, argb >> 8 & BIT_MASK, argb & BIT_MASK);
     }
 
@@ -191,16 +206,16 @@ public final class Color implements ConfigurationSerializable {
      *     bits
      */
     @NotNull
-    public static Color fromBGR(int bgr) throws IllegalArgumentException {
+    public static Color fromBGR(final int bgr) throws IllegalArgumentException {
         Preconditions.checkArgument((bgr >> 24) == 0, "Extrenuous data in: %s", bgr);
         return fromBGR(bgr >> 16 & BIT_MASK, bgr >> 8 & BIT_MASK, bgr & BIT_MASK);
     }
 
-    private Color(int red, int green, int blue) {
+    private Color(final int red, final int green, final int blue) {
         this(DEFAULT_ALPHA, red, green, blue);
     }
 
-    private Color(int alpha, int red, int green, int blue) {
+    private Color(final int alpha, final int red, final int green, final int blue) {
         Preconditions.checkArgument(alpha >= 0 && alpha <= 0xff, "Alpha[%s] is not between 0-255", alpha);
         Preconditions.checkArgument(red >= 0 && red <= 0xff, "Red[%s] is not between 0-255", red);
         Preconditions.checkArgument(green >= 0 && green <= 0xff, "Green[%s] is not between 0-255", green);
@@ -213,83 +228,123 @@ public final class Color implements ConfigurationSerializable {
     }
 
     /**
-     * Gets the alpha component
+     * Gets the alpha component.
      *
      * @return alpha component, from 0 to 255
      */
-    public int getAlpha() {
+    public @Range(from = 0, to = 255) int getAlpha() {
         return BIT_MASK & alpha;
     }
 
     /**
-     * Creates a new Color object with specified component
+     * Gets the alpha component.
+     *
+     * @return alpha component, from 0 to 255
+     */
+    @Override
+    public @Range(from = 0, to = 255) int alpha() {
+        return this.getAlpha();
+    }
+
+    /**
+     * Creates a new Color object with a specified component.
      *
      * @param alpha the alpha component, from 0 to 255
      * @return a new color object with the alpha component
      */
     @NotNull
-    public Color setAlpha(int alpha) {
-        return fromARGB(alpha, getRed(), getGreen(), getBlue());
+    public Color setAlpha(final @Range(from = 0, to = 255) int alpha) {
+        return fromARGB(alpha, this.getRed(), this.getGreen(), this.getBlue());
     }
 
     /**
-     * Gets the red component
+     * Gets the red component.
      *
      * @return red component, from 0 to 255
      */
-    public int getRed() {
-        return BIT_MASK & red;
+    public @Range(from = 0, to = 255) int getRed() {
+        return BIT_MASK & this.red;
     }
 
     /**
-     * Creates a new Color object with specified component
+     * Gets the red component.
+     *
+     * @return red component, from 0 to 255
+     */
+    @Override
+    public @Range(from = 0, to = 255) int red() {
+        return this.getRed();
+    }
+
+    /**
+     * Creates a new Color object with a specified component.
      *
      * @param red the red component, from 0 to 255
      * @return a new color object with the red component
      */
     @NotNull
-    public Color setRed(int red) {
-        return fromARGB(getAlpha(), red, getGreen(), getBlue());
+    public Color setRed(final @Range(from = 0, to = 255) int red) {
+        return fromARGB(this.getAlpha(), red, this.getGreen(), this.getBlue());
     }
 
     /**
-     * Gets the green component
+     * Gets the green component.
      *
      * @return green component, from 0 to 255
      */
-    public int getGreen() {
-        return BIT_MASK & green;
+    public @Range(from = 0, to = 255) int getGreen() {
+        return BIT_MASK & this.green;
     }
 
     /**
-     * Creates a new Color object with specified component
+     * Gets the green component.
+     *
+     * @return green component, from 0 to 255
+     */
+    @Override
+    public @Range(from = 0, to = 255) int green() {
+        return this.getGreen();
+    }
+
+    /**
+     * Creates a new Color object with a specified component.
      *
      * @param green the green component, from 0 to 255
      * @return a new color object with the green component
      */
     @NotNull
-    public Color setGreen(int green) {
-        return fromARGB(getAlpha(), getRed(), green, getBlue());
+    public Color setGreen(final @Range(from = 0, to = 255) int green) {
+        return fromARGB(this.getAlpha(), this.getRed(), green, this.getBlue());
     }
 
     /**
-     * Gets the blue component
+     * Gets the blue component.
      *
      * @return blue component, from 0 to 255
      */
-    public int getBlue() {
-        return BIT_MASK & blue;
+    public @Range(from = 0, to = 255) int getBlue() {
+        return BIT_MASK & this.blue;
     }
 
     /**
-     * Creates a new Color object with specified component
+     * Gets the blue component.
+     *
+     * @return blue component, from 0 to 255
+     */
+    @Override
+    public @Range(from = 0, to = 255) int blue() {
+        return this.getBlue();
+    }
+
+    /**
+     * Creates a new Color object with a specified component.
      *
      * @param blue the blue component, from 0 to 255
      * @return a new color object with the blue component
      */
     @NotNull
-    public Color setBlue(int blue) {
-        return fromARGB(getAlpha(), getRed(), getGreen(), blue);
+    public Color setBlue(final @Range(from = 0, to = 255) int blue) {
+        return fromARGB(this.getAlpha(), this.getRed(), this.getGreen(), blue);
     }
 
     /**
@@ -298,7 +353,7 @@ public final class Color implements ConfigurationSerializable {
      * @return An integer representation of this color, as 0xRRGGBB
      */
     public int asRGB() {
-        return getRed() << 16 | getGreen() << 8 | getBlue();
+        return this.getRed() << 16 | this.getGreen() << 8 | this.getBlue();
     }
 
     /**
@@ -307,7 +362,7 @@ public final class Color implements ConfigurationSerializable {
      * @return An integer representation of this color, as 0xAARRGGBB
      */
     public int asARGB() {
-        return getAlpha() << 24 | getRed() << 16 | getGreen() << 8 | getBlue();
+        return this.getAlpha() << 24 | this.getRed() << 16 | this.getGreen() << 8 | this.getBlue();
     }
 
     /**
@@ -316,33 +371,33 @@ public final class Color implements ConfigurationSerializable {
      * @return An integer representation of this color, as 0xBBGGRR
      */
     public int asBGR() {
-        return getBlue() << 16 | getGreen() << 8 | getRed();
-    }
-
-    /**
-     * Creates a new color with its RGB components changed as if it was dyed
-     * with the colors passed in, replicating vanilla workbench dyeing
-     *
-     * @param colors The DyeColors to dye with
-     * @return A new color with the changed rgb components
-     */
-    // TODO: Javadoc what this method does, not what it mimics. API != Implementation
-    @NotNull
-    public Color mixDyes(@NotNull DyeColor... colors) {
-        Preconditions.checkArgument(colors != null && Arrays.stream(colors).allMatch(Objects::nonNull), "DyeColor cannot be null or contain null values");
-
-        Color[] toPass = new Color[colors.length];
-        for (int i = 0; i < colors.length; i++) {
-            toPass[i] = colors[i].getColor();
-        }
-
-        return mixColors(toPass);
+        return this.getBlue() << 16 | this.getGreen() << 8 | this.getRed();
     }
 
     /**
      * Creates a new color with its RGB components changed as if it was dyed
      * with the colors passed in, replicating vanilla workbench dyeing.
      *
+     * @param colors The DyeColors to dye with
+     * @return A new color with the changed rgb components
+     */
+    // TODO: Javadoc what this method does, not what it mimics. API != Implementation
+    @NotNull
+    public Color mixDyes(final @NotNull DyeColor... colors) {
+        Preconditions.checkArgument(colors != null && Arrays.stream(colors).allMatch(Objects::nonNull), "DyeColor cannot be null or contain null values");
+
+        final Color[] toPass = new Color[colors.length];
+        for (int i = 0; i < colors.length; i++) {
+            toPass[i] = colors[i].getColor();
+        }
+
+        return this.mixColors(toPass);
+    }
+
+    /**
+     * Creates a new color with its RGB components changed as if it was dyed
+     * with the colors passed in, replicating vanilla workbench dyeing.
+     * <br>
      * <b>Note that this method does not currently take into account alpha
      * components.</b>
      *
@@ -351,7 +406,7 @@ public final class Color implements ConfigurationSerializable {
      */
     // TODO: Javadoc what this method does, not what it mimics. API != Implementation
     @NotNull
-    public Color mixColors(@NotNull Color... colors) {
+    public Color mixColors(final @NotNull Color... colors) {
         Preconditions.checkArgument(colors != null && Arrays.stream(colors).allMatch(Objects::nonNull), "Colors cannot be null");
 
         int totalRed = this.getRed();
@@ -365,44 +420,43 @@ public final class Color implements ConfigurationSerializable {
             totalMax += Math.max(Math.max(color.getRed(), color.getGreen()), color.getBlue());
         }
 
-        float averageRed = totalRed / (colors.length + 1);
-        float averageGreen = totalGreen / (colors.length + 1);
-        float averageBlue = totalBlue / (colors.length + 1);
-        float averageMax = totalMax / (colors.length + 1);
+        final float averageRed = totalRed / (colors.length + 1);
+        final float averageGreen = totalGreen / (colors.length + 1);
+        final float averageBlue = totalBlue / (colors.length + 1);
+        final float averageMax = totalMax / (colors.length + 1);
 
-        float maximumOfAverages = Math.max(Math.max(averageRed, averageGreen), averageBlue);
-        float gainFactor = averageMax / maximumOfAverages;
+        final float maximumOfAverages = Math.max(Math.max(averageRed, averageGreen), averageBlue);
+        final float gainFactor = averageMax / maximumOfAverages;
 
         return Color.fromRGB((int) (averageRed * gainFactor), (int) (averageGreen * gainFactor), (int) (averageBlue * gainFactor));
     }
 
     @Override
-    public boolean equals(Object o) {
-        if (!(o instanceof Color)) {
+    public boolean equals(final Object o) {
+        if (!(o instanceof Color that)) {
             return false;
         }
-        final Color that = (Color) o;
         return this.alpha == that.alpha && this.blue == that.blue && this.green == that.green && this.red == that.red;
     }
 
     @Override
     public int hashCode() {
-        return asARGB() ^ Color.class.hashCode();
+        return this.asARGB() ^ Color.class.hashCode();
     }
 
     @Override
     @NotNull
     public Map<String, Object> serialize() {
         return ImmutableMap.of(
-                "ALPHA", getAlpha(),
-                "RED", getRed(),
-                "BLUE", getBlue(),
-                "GREEN", getGreen()
+                "ALPHA", this.getAlpha(),
+                "RED", this.getRed(),
+                "BLUE", this.getBlue(),
+                "GREEN", this.getGreen()
         );
     }
 
     @NotNull
-    public static Color deserialize(@NotNull Map<String, Object> map) {
+    public static Color deserialize(final @NotNull Map<String, Object> map) {
         return fromARGB(
                 asInt("ALPHA", map, DEFAULT_ALPHA),
                 asInt("RED", map),
@@ -411,23 +465,23 @@ public final class Color implements ConfigurationSerializable {
         );
     }
 
-    private static int asInt(@NotNull String string, @NotNull Map<String, Object> map) {
+    private static int asInt(final @NotNull String string, final @NotNull Map<String, Object> map) {
         return asInt(string, map, null);
     }
 
-    private static int asInt(@NotNull String string, @NotNull Map<String, Object> map, @Nullable Object defaultValue) {
-        Object value = map.getOrDefault(string, defaultValue);
+    private static int asInt(final @NotNull String string, final @NotNull Map<String, Object> map, final @Nullable Object defaultValue) {
+        final Object value = map.getOrDefault(string, defaultValue);
         if (value == null) {
             throw new IllegalArgumentException(string + " not in map " + map);
         }
-        if (!(value instanceof Number)) {
+        if (!(value instanceof Number number)) {
             throw new IllegalArgumentException(string + '(' + value + ") is not a number");
         }
-        return ((Number) value).intValue();
+        return number.intValue();
     }
 
     @Override
     public String toString() {
-        return "Color:[argb0x" + Integer.toHexString(asARGB()).toUpperCase(Locale.ROOT) + "]";
+        return "Color:[argb0x" + Integer.toHexString(this.asARGB()).toUpperCase(Locale.ROOT) + "]";
     }
 }

paper-api/src/main/java/org/bukkit/Server.java

@@ -61,6 +61,8 @@ import org.bukkit.profile.PlayerProfile;
 import org.bukkit.scheduler.BukkitScheduler;
 import org.bukkit.scoreboard.Criteria;
 import org.bukkit.scoreboard.ScoreboardManager;
+import org.bukkit.generator.structure.Structure;
+import org.bukkit.map.MapCursor;
 import org.bukkit.structure.StructureManager;
 import org.bukkit.util.CachedServerIcon;
 import org.jetbrains.annotations.ApiStatus;
@@ -872,8 +874,7 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * Create a new explorer map targeting the closest nearby structure of a
      * given {@link StructureType}.
      * <br>
-     * This method uses implementation default values for radius and
-     * findUnexplored (usually 100, true).
+     * This method uses a radius of 100 and only searches for unexplored structures.
      *
      * @param world the world the map will belong to
      * @param location the origin location to find the nearest structure
@@ -882,9 +883,9 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      *
      * @see World#locateNearestStructure(org.bukkit.Location,
      *      org.bukkit.StructureType, int, boolean)
-     * @deprecated use {@link #createExplorerMap(World, Location, org.bukkit.generator.structure.StructureType, org.bukkit.map.MapCursor.Type)}
+     * @deprecated use {@link #createExplorerMap(World, Location, org.bukkit.generator.structure.StructureType, MapCursor.Type)}
      */
-    @Deprecated // Paper
+    @Deprecated
     @NotNull
     default ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType) {
         return this.createExplorerMap(world, location, structureType, 100, true);
@@ -904,18 +905,16 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      *
      * @see World#locateNearestStructure(org.bukkit.Location,
      *      org.bukkit.StructureType, int, boolean)
-     * @deprecated use {@link #createExplorerMap(World, Location, org.bukkit.generator.structure.StructureType, org.bukkit.map.MapCursor.Type, int, boolean)}
+     * @deprecated use {@link #createExplorerMap(World, Location, org.bukkit.generator.structure.StructureType, MapCursor.Type, int, boolean)}
      */
-    @Deprecated // Paper
-    @NotNull
-    public ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType, int radius, boolean findUnexplored);
-    // Paper start
+    @Deprecated
+    @NotNull ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType, int radius, boolean findUnexplored);
+
     /**
      * Create a new explorer map targeting the closest nearby structure of a
-     * given {@link org.bukkit.generator.structure.StructureType}.
+     * given {@link StructureType}.
      * <br>
-     * This method uses implementation default values for radius and
-     * findUnexplored (usually 100, true).
+     * This method uses a radius of 100 and only searches for unexplored structures.
      *
      * @param world the world the map will belong to
      * @param location the origin location to find the nearest structure
@@ -924,15 +923,15 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * @return a newly created item stack or null if it can't find a location
      *
      * @see World#locateNearestStructure(org.bukkit.Location,
-     *      org.bukkit.generator.structure.StructureType, int, boolean)
+     *      StructureType, int, boolean)
      */
-    default @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull org.bukkit.generator.structure.StructureType structureType, @NotNull org.bukkit.map.MapCursor.Type mapIcon) {
+    default @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull org.bukkit.generator.structure.StructureType structureType, @NotNull MapCursor.Type mapIcon) {
         return this.createExplorerMap(world, location, structureType, mapIcon, 100, true);
     }
 
     /**
      * Create a new explorer map targeting the closest nearby structure of a
-     * given {@link org.bukkit.generator.structure.StructureType}.
+     * given {@link StructureType}.
      *
      * @param world the world the map will belong to
      * @param location the origin location to find the nearest structure
@@ -944,10 +943,46 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * @return the newly created item stack or null if it can't find a location
      *
      * @see World#locateNearestStructure(org.bukkit.Location,
-     *      org.bukkit.generator.structure.StructureType, int, boolean)
+     *      StructureType, int, boolean)
      */
-    @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull org.bukkit.generator.structure.StructureType structureType, @NotNull org.bukkit.map.MapCursor.Type mapIcon, int radius, boolean findUnexplored);
-    // Paper end
+    @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull org.bukkit.generator.structure.StructureType structureType, @NotNull MapCursor.Type mapIcon, int radius, boolean findUnexplored);
+
+    /**
+     * Create a new explorer map targeting the closest nearby specific
+     * {@link Structure}.
+     * <br>
+     * This method uses a radius of 100 and only searches for unexplored structures.
+     *
+     * @param world the world the map will belong to
+     * @param location the origin location to find the nearest structure
+     * @param structure the specific structure to find
+     * @param mapIcon the map icon to use on the map
+     * @return a newly created item stack or null if it can't find a location
+     *
+     * @see World#locateNearestStructure(org.bukkit.Location,
+     *      Structure, int, boolean)
+     */
+    default @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull Structure structure, @NotNull MapCursor.Type mapIcon) {
+        return this.createExplorerMap(world, location, structure, mapIcon, 100, true);
+    }
+
+    /**
+     * Create a new explorer map targeting the closest nearby specific
+     * {@link Structure}.
+     *
+     * @param world the world the map will belong to
+     * @param location the origin location to find the nearest structure
+     * @param structure the specific structure to find
+     * @param mapIcon the map icon to use on the map
+     * @param radius radius to search, see World#locateNearestStructure for more
+     *               information
+     * @param findUnexplored whether to find unexplored structures
+     * @return the newly created item stack or null if it can't find a location
+     *
+     * @see World#locateNearestStructure(org.bukkit.Location,
+     *      Structure, int, boolean)
+     */
+    @Nullable ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull Structure structure, @NotNull MapCursor.Type mapIcon, int radius, boolean findUnexplored);
 
     /**
      * Reloads the server, refreshing settings and plugin information.
@@ -995,7 +1030,11 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      *
      * @param name the name of the command to retrieve
      * @return a plugin command if found, null otherwise
+     * @apiNote plugin developers should prefer to use the
+     *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+     *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
      */
+    @ApiStatus.Obsolete(since = "26.3")
     @Nullable
     public PluginCommand getPluginCommand(@NotNull String name);
 
@@ -1018,32 +1057,44 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
 
     /**
      * Adds a recipe to the crafting manager.
-     * Recipes added with this method won't be sent to the client automatically.
+     * Recipes added with this method will be sent to the client automatically.
      * <p>
      * Players still have to discover recipes via {@link Player#discoverRecipe(NamespacedKey)}
      * before seeing them in their recipe book.
      *
      * @param recipe the recipe to add
      * @return true if the recipe was added, false if it wasn't for some reason
-     * @see #addRecipe(Recipe, boolean)
+     * @throws IllegalStateException if the recipe is already added to the crafting manager
      */
     @Contract("null -> false")
-    default boolean addRecipe(@Nullable Recipe recipe) {
-        return this.addRecipe(recipe, false);
-    }
+    boolean addRecipe(@Nullable Recipe recipe);
 
-    // Paper start - method to send recipes immediately
     /**
      * Adds a recipe to the crafting manager.
      *
-     * @apiNote resendRecipes is ignored for now for stability reasons, recipes will always be updated
      * @param recipe the recipe to add
-     * @param resendRecipes true to update the client with the full set of recipes
+     * @param resendRecipes ignored, refer to the deprecation note
      * @return true if the recipe was added, false if it wasn't for some reason
+     * @throws IllegalStateException if the recipe is already added to the crafting manager
+     * @deprecated use {@link #addRecipe(Recipe)} instead, as Minecraft always resends recipes on a recipe added
      */
+    @Deprecated(since = "26.3")
     @Contract("null, _ -> false")
-    boolean addRecipe(@Nullable Recipe recipe, boolean resendRecipes);
-    // Paper end - method to send recipes immediately
+    default boolean addRecipe(@Nullable Recipe recipe, boolean resendRecipes) {
+        return this.addRecipe(recipe);
+    }
+
+    /**
+     * Adds multiple recipes to the crafting manager at once, resending recipes only once
+     * after all have been added.
+     *
+     * @apiNote This method differs from {@link #addRecipe} in that it will only resend the recipe book once instead of once per every recipe added
+     * @param recipes the recipes to add
+     * @return true if any recipe was added, false if none were for some reason
+     * @throws IllegalStateException if any of the recipes are already added to the crafting manager
+     * @see #addRecipe
+     */
+    boolean addRecipes(@NotNull Iterable<Recipe> recipes);
 
     /**
      * Get a list of all recipes for a given item. The stack size is ignored
@@ -1205,6 +1256,14 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      */
     public void resetRecipes();
 
+    /**
+     * Checks if the server has a recipe
+     *
+     * @param key NamespacedKey of recipe to check for
+     * @return True if there is a recipe with a matching key
+     */
+    boolean hasRecipe(@NotNull NamespacedKey key);
+
     /**
      * Remove a recipe from the server.
      *
@@ -1215,11 +1274,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * @param key NamespacedKey of recipe to remove.
      * @return True if recipe was removed
      */
-    default boolean removeRecipe(@NotNull NamespacedKey key) {
-        return this.removeRecipe(key, false);
-    }
+    boolean removeRecipe(@NotNull NamespacedKey key);
 
-    // Paper start - method to resend recipes
     /**
      * Remove a recipe from the server.
      * <p>
@@ -1228,12 +1284,24 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * players).</b>
      *
      * @param key NamespacedKey of recipe to remove.
-     * @param resendRecipes true to update all clients on the new recipe list.
-     *                      Will only update if a recipe was actually removed
+     * @param resendRecipes ignored, refer to the deprecation note
      * @return True if recipe was removed
+     * @deprecated use {@link #removeRecipe(NamespacedKey)} instead, as Minecraft always resends recipes on recipe removal
      */
-    boolean removeRecipe(@NotNull NamespacedKey key, boolean resendRecipes);
-    // Paper end - method to resend recipes
+    @Deprecated(since = "26.3")
+    default boolean removeRecipe(@NotNull NamespacedKey key, boolean resendRecipes) {
+        return this.removeRecipe(key);
+    }
+
+    /**
+     * Remove multiple recipes from the server.
+     *
+     * @apiNote This method differs from {@link #removeRecipe} in that it will only resend the recipe book once instead of once per every recipe removed
+     * @param keys the NamespacedKeys of the recipes to remove
+     * @return true if any recipe was removed, false if none were for some reason
+     * @see #removeRecipe
+     */
+    boolean removeRecipes(@NotNull Iterable<NamespacedKey> keys);
 
     /**
      * Gets a list of command aliases defined in the server properties.
@@ -2207,7 +2275,11 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * Gets the active {@link org.bukkit.command.CommandMap}
      *
      * @return the active command map
+     * @apiNote plugin developers should prefer to use the
+     *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+     *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
      */
+    @ApiStatus.Obsolete(since = "26.3")
     @NotNull
     org.bukkit.command.CommandMap getCommandMap();
 

paper-api/src/main/java/org/bukkit/TreeType.java

@@ -110,7 +110,15 @@ public enum TreeType {
      */
     PALE_OAK_CREAKING,
     /**
-     * Poplar tree
+     * Poplar tree with red leaves
      */
-    POPLAR,
+    RED_POPLAR,
+    /**
+     * Poplar tree with orange leaves
+     */
+    ORANGE_POPLAR,
+    /**
+     * Poplar tree with yellow leaves
+     */
+    YELLOW_POPLAR,
 }

paper-api/src/main/java/org/bukkit/Warning.java

@@ -23,7 +23,7 @@ public @interface Warning {
     /**
      * This represents the states that server verbose for warnings may be.
      */
-    public enum WarningState {
+    enum WarningState {
 
         /**
          * Indicates all warnings should be printed for deprecated items.
@@ -100,14 +100,23 @@ public @interface Warning {
      * This sets if the deprecation warnings when registering events gets
      * printed when the setting is in the default state.
      *
-     * @return false normally, or true to encourage warning printout
+     * @return {@code false} normally, or {@code true} to encourage warning printout
      */
     boolean value() default false;
 
     /**
      * This can provide detailed information on why the event is deprecated.
      *
-     * @return The reason an event is deprecated
+     * @return the reason an event is deprecated
      */
     String reason() default "";
+
+    /**
+     * This indicate if the deprecation warnings should propagate to sub events or not.
+     * The default is {@code true} only to maintains compatibility but it's recommended
+     * to use {@code false} for more explicit behavior.
+     *
+     * @return whether to propagate the deprecation warnings
+     */
+    boolean propagate() default true;
 }

paper-api/src/main/java/org/bukkit/World.java

@@ -4,6 +4,8 @@ import io.papermc.paper.entity.poi.PoiSearchResult;
 import io.papermc.paper.entity.poi.PoiType;
 import io.papermc.paper.math.Position;
 import io.papermc.paper.raytracing.PositionedRayTraceConfigurationBuilder;
+import io.papermc.paper.world.WorldClock;
+import io.papermc.paper.world.chunk.ChunkGenerationState;
 import java.io.File;
 import java.nio.file.Path;
 import java.util.ArrayList;
@@ -12,6 +14,7 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
 import org.bukkit.block.Biome;
@@ -394,6 +397,58 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      */
     public boolean isChunkGenerated(int x, int z);
 
+    /**
+     * Checks the generation state of the {@link Chunk} at the specified coordinates
+     * without loading it, blocking until the state is known.
+     *
+     * <p>
+     * This may read chunk data from disk, which blocks the calling thread. Prefer
+     * {@link #getChunkGenerationStateAsync(int, int)} where possible.
+     * </p>
+     *
+     * <p>
+     * The result is a snapshot: the chunk may be generated, loaded, or saved
+     * concurrently, so the state may be stale by the time it is observed.
+     * </p>
+     *
+     * @param x X-coordinate of the chunk
+     * @param z Z-coordinate of the chunk
+     * @return the generation state of the chunk
+     * @throws RuntimeException if the chunk data cannot be read, or if it was saved
+     *     by a newer version of the game
+     */
+    @NotNull ChunkGenerationState getChunkGenerationState(int x, int z);
+
+    /**
+     * Checks the generation state of the {@link Chunk} at the specified coordinates
+     * without loading it.
+     *
+     * <p>
+     * The result is a snapshot: the chunk may be generated, loaded, or saved
+     * concurrently, so the state may be stale by the time it is observed.
+     * </p>
+     *
+     * <p>
+     * The returned future is completed on an unspecified thread. Callers that need to
+     * interact with the world should move to the appropriate thread themselves.
+     * </p>
+     *
+     * <p>
+     * If the main thread will block on the result, use {@link #getChunkGenerationState(int, int)}
+     * instead, which reads the chunk data at a priority suitable for blocking.
+     * </p>
+     *
+     * <p>
+     * The future is completed exceptionally if the chunk data cannot be read, or if
+     * it was saved by a newer version of the game.
+     * </p>
+     *
+     * @param x X-coordinate of the chunk
+     * @param z Z-coordinate of the chunk
+     * @return a future completed with the generation state of the chunk
+     */
+    @NotNull CompletableFuture<@NotNull ChunkGenerationState> getChunkGenerationStateAsync(int x, int z);
+
     /**
      * Checks if the {@link Chunk} at the specified coordinates is loaded and
      * in use by one or more players
@@ -2062,7 +2117,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The current relative time
      * @see #getFullTime() Returns an absolute time of this world
      */
-    public long getTime();
+    long getTime();
 
     /**
      * Sets the relative in-game time on the server.
@@ -2077,7 +2132,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     hours*1000)
      * @see #setFullTime(long) Sets the absolute time of this world
      */
-    public void setTime(long time);
+    void setTime(long time);
 
     /**
      * Gets the full in-game time on this world, or {@code 0} if this world does not have a world clock.
@@ -2085,7 +2140,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The current absolute time
      * @see #getTime() Returns a relative time of this world
      */
-    public long getFullTime();
+    long getFullTime();
 
     /**
      * Sets the in-game time on the server
@@ -2097,7 +2152,69 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @see #setTime(long) Sets the relative time of this world
      * @throws IllegalArgumentException if this world does not have a world clock (e.g. the nether)
      */
-    public void setFullTime(long time);
+    void setFullTime(long time);
+
+    /**
+     * Gets the default clock of this world's dimension type.
+     * <p>
+     * This is the clock used by {@link #getTime()}, {@link #getFullTime()} and their setters.
+     *
+     * @return the default clock, or {@code null} if this world does not have one (e.g. the nether)
+     */
+    @Nullable WorldClock getDefaultClock();
+
+    /**
+     * Gets the total number of ticks the given clock has advanced in this world.
+     * <p>
+     * Clocks are per world unless the server is configured to share them between all worlds.
+     *
+     * @param clock the clock
+     * @return the total ticks of the clock
+     */
+    long getFullTime(@NotNull WorldClock clock);
+
+    /**
+     * Sets the total number of ticks of the given clock in this world.
+     * <p>
+     * This calls a {@link org.bukkit.event.world.ClockTimeSkipEvent} and does nothing if it is cancelled.
+     * Clocks are per world unless the server is configured to share them between all worlds.
+     *
+     * @param clock the clock
+     * @param time the new total ticks of the clock, must not be negative
+     */
+    void setFullTime(@NotNull WorldClock clock, long time);
+
+    /**
+     * Gets whether the given clock is paused in this world.
+     *
+     * @param clock the clock
+     * @return whether the clock is paused
+     */
+    boolean isClockPaused(@NotNull WorldClock clock);
+
+    /**
+     * Sets whether the given clock is paused in this world.
+     *
+     * @param clock the clock
+     * @param paused whether the clock should be paused
+     */
+    void setClockPaused(@NotNull WorldClock clock, boolean paused);
+
+    /**
+     * Gets the rate at which the given clock advances in this world, in clock ticks per game tick.
+     *
+     * @param clock the clock
+     * @return the clock rate
+     */
+    float getClockRate(@NotNull WorldClock clock);
+
+    /**
+     * Sets the rate at which the given clock advances in this world, in clock ticks per game tick.
+     *
+     * @param clock the clock
+     * @param rate the new clock rate, must be positive
+     */
+    void setClockRate(@NotNull WorldClock clock, float rate);
 
     // Paper start
 

paper-api/src/main/java/org/bukkit/block/BlockType.java

@@ -4,6 +4,7 @@ import java.util.Collection;
 import java.util.function.Consumer;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.key.KeyPattern;
+import org.bukkit.Instrument;
 import org.bukkit.Keyed;
 import org.bukkit.Material;
 import org.bukkit.Registry;
@@ -2986,4 +2987,12 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      * @return false if this block never has collision, true if it <b>might</b> have collision
      */
     boolean hasCollision();
+
+    /**
+     * Gets the {@link Instrument} associated with this block.
+     * This determines the instrument sound that would be played if a Note Block were placed directly above or below this block.
+     *
+     * @return the associated instrument
+     */
+    Instrument getInstrument();
 }

paper-api/src/main/java/org/bukkit/block/data/AttachableDirectional.java

@@ -0,0 +1,27 @@
+package org.bukkit.block.data;
+
+import org.bukkit.block.BlockFace;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A marker interface for block data that is both {@link FaceAttachable} and {@link Directional}.
+ * <p>
+ * This represents blocks that are mounted on a specific face of another block (e.g., buttons, levers)
+ * and also have a facing direction.
+ */
+@NullMarked
+public interface AttachableDirectional extends FaceAttachable, Directional {
+
+    /**
+     * Gets the {@link BlockFace} of the block that this block is physically attached to.
+     * This is determined by the attached face.
+     * @return the block face to which this block is attached
+     */
+    default BlockFace getAttachedBlockFace() {
+        return switch (this.getAttachedFace()) {
+            case FLOOR -> BlockFace.DOWN;
+            case CEILING -> BlockFace.UP;
+            case WALL -> this.getFacing().getOppositeFace();
+        };
+    }
+}

paper-api/src/main/java/org/bukkit/block/data/BlockData.java

@@ -13,7 +13,6 @@ import org.bukkit.block.PistonMoveReaction;
 import org.bukkit.block.structure.Mirror;
 import org.bukkit.block.structure.StructureRotation;
 import org.bukkit.inventory.ItemStack;
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 

paper-api/src/main/java/org/bukkit/block/data/type/Grindstone.java

@@ -1,7 +1,6 @@
 package org.bukkit.block.data.type;
 
-import org.bukkit.block.data.Directional;
-import org.bukkit.block.data.FaceAttachable;
+import org.bukkit.block.data.AttachableDirectional;
 
-public interface Grindstone extends Directional, FaceAttachable {
+public interface Grindstone extends AttachableDirectional {
 }

paper-api/src/main/java/org/bukkit/block/data/type/Switch.java

@@ -1,11 +1,10 @@
 package org.bukkit.block.data.type;
 
-import org.bukkit.block.data.Directional;
-import org.bukkit.block.data.FaceAttachable;
+import org.bukkit.block.data.AttachableDirectional;
 import org.bukkit.block.data.Powerable;
 import org.jetbrains.annotations.NotNull;
 
-public interface Switch extends Directional, FaceAttachable, Powerable {
+public interface Switch extends AttachableDirectional, Powerable {
 
     @NotNull
     AttachedFace getAttachedFace();

paper-api/src/main/java/org/bukkit/command/Command.java

@@ -15,12 +15,18 @@ import org.bukkit.entity.minecart.CommandMinecart;
 import org.bukkit.permissions.Permissible;
 import org.bukkit.plugin.PluginDescriptionFile;
 import org.bukkit.util.StringUtil;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a Command, which executes various tasks upon user input
+ *
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
  */
+@ApiStatus.Obsolete(since = "26.3")
 public abstract class Command {
     private String name;
     private String nextLabel;

paper-api/src/main/java/org/bukkit/command/CommandExecutor.java

@@ -1,10 +1,16 @@
 package org.bukkit.command;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a class which contains a single method for executing commands
+ *
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
  */
+@ApiStatus.Obsolete(since = "26.3")
 public interface CommandExecutor {
 
     /**
@@ -18,6 +24,10 @@ public interface CommandExecutor {
      * @param label Alias of the command which was used
      * @param args Passed command arguments
      * @return true if a valid command, otherwise false
+     * @apiNote plugin developers should prefer to use the
+     *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+     *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
      */
+    @ApiStatus.Obsolete(since = "26.3")
     public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command, @NotNull String label, @NotNull String @NotNull [] args);
 }

paper-api/src/main/java/org/bukkit/command/CommandMap.java

@@ -2,9 +2,16 @@ package org.bukkit.command;
 
 import java.util.List;
 import org.bukkit.Location;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
+ */
+@ApiStatus.Obsolete(since = "26.3")
 public interface CommandMap {
 
     /**

paper-api/src/main/java/org/bukkit/command/FormattedCommandAlias.java

@@ -7,8 +7,15 @@ import java.util.regex.Pattern; // Paper
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.format.NamedTextColor;
 import org.bukkit.Bukkit;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
+ */
+@ApiStatus.Obsolete(since = "26.3")
 public class FormattedCommandAlias extends Command {
     private final String[] formatStrings;
 

paper-api/src/main/java/org/bukkit/command/MultipleCommandAlias.java

@@ -1,10 +1,16 @@
 package org.bukkit.command;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a command that delegates to one or more other commands
+ *
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
  */
+@ApiStatus.Obsolete(since = "26.3")
 public class MultipleCommandAlias extends Command {
     private Command[] commands;
 

paper-api/src/main/java/org/bukkit/command/PluginCommand.java

@@ -3,12 +3,18 @@ package org.bukkit.command;
 import com.google.common.base.Preconditions;
 import java.util.List;
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a {@link Command} belonging to a plugin
+ *
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
  */
+@ApiStatus.Obsolete(since = "26.3")
 public final class PluginCommand extends Command implements PluginIdentifiableCommand {
     private final Plugin owningPlugin;
     private CommandExecutor executor;

paper-api/src/main/java/org/bukkit/command/PluginCommandYamlParser.java

@@ -6,8 +6,15 @@ import java.util.Map;
 import java.util.Map.Entry;
 import org.bukkit.Bukkit;
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
+ */
+@ApiStatus.Obsolete(since = "26.3")
 public class PluginCommandYamlParser {
 
     @NotNull

paper-api/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java

@@ -1,6 +1,7 @@
 package org.bukkit.command;
 
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -8,7 +9,12 @@ import org.jetbrains.annotations.NotNull;
  * sub-indexes based on the {@link Plugin} they are a part of. Custom command
  * implementations will need to implement this interface to have a sub-index
  * automatically generated on the plugin's behalf.
+ *
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
  */
+@ApiStatus.Obsolete(since = "26.3")
 public interface PluginIdentifiableCommand {
 
     /**

paper-api/src/main/java/org/bukkit/command/SimpleCommandMap.java

@@ -16,9 +16,16 @@ import org.bukkit.command.defaults.HelpCommand;
 import org.bukkit.command.defaults.ReloadCommand;
 import org.bukkit.entity.Player;
 import org.bukkit.util.StringUtil;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
+ */
+@ApiStatus.Obsolete(since = "26.3")
 public class SimpleCommandMap implements CommandMap {
     protected final Map<String, Command> knownCommands;
     private final Server server;

paper-api/src/main/java/org/bukkit/command/TabCompleter.java

@@ -1,12 +1,18 @@
 package org.bukkit.command;
 
 import java.util.List;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a class which can suggest tab completions for commands.
+ *
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
  */
+@ApiStatus.Obsolete(since = "26.3")
 public interface TabCompleter {
 
     /**
@@ -21,7 +27,11 @@ public interface TabCompleter {
      *     partial argument to be completed
      * @return A List of possible completions for the final argument, or null
      *     to default to the command executor
+     * @apiNote plugin developers should prefer to use the
+     *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+     *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
      */
+    @ApiStatus.Obsolete(since = "26.3")
     @Nullable
     public List<String> onTabComplete(@NotNull CommandSender sender, @NotNull Command command, @NotNull String label, @NotNull String @NotNull [] args);
 }

paper-api/src/main/java/org/bukkit/command/TabExecutor.java

@@ -1,8 +1,15 @@
 package org.bukkit.command;
 
+import org.jetbrains.annotations.ApiStatus;
+
 /**
  * This class is provided as a convenience to implement both TabCompleter and
  * CommandExecutor.
+ *
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
  */
+@ApiStatus.Obsolete(since = "26.3")
 public interface TabExecutor extends TabCompleter, CommandExecutor {
 }

paper-api/src/main/java/org/bukkit/command/defaults/BukkitCommand.java

@@ -2,8 +2,15 @@ package org.bukkit.command.defaults;
 
 import java.util.List;
 import org.bukkit.command.Command;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * @apiNote plugin developers should prefer to use the
+ *     <a href="https://docs.papermc.io/paper/dev/command-api/basics/introduction/">Brigadier command API</a>.
+ *     For a direct alternative to Bukkit commands, <a href="https://docs.papermc.io/paper/dev/command-api/misc/basic-command/">Basic commands</a> are recommended
+ */
+@ApiStatus.Obsolete(since = "26.3")
 public abstract class BukkitCommand extends Command {
     protected BukkitCommand(@NotNull String name) {
         super(name);

paper-api/src/main/java/org/bukkit/enchantments/EnchantmentOffer.java

@@ -1,18 +1,26 @@
 package org.bukkit.enchantments;
 
 import com.google.common.base.Preconditions;
-import org.jetbrains.annotations.NotNull;
+import io.papermc.paper.InternalAPIBridge;
+import org.bukkit.inventory.ItemStack;
+import java.util.Objects;
+import org.checkerframework.checker.index.qual.Positive;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import static io.papermc.paper.util.BoundChecker.requirePositive;
 
 /**
  * A class for the available enchantment offers in the enchantment table.
  */
+@NullMarked
 public class EnchantmentOffer {
 
     private Enchantment enchantment;
     private int enchantmentLevel;
     private int cost;
 
-    public EnchantmentOffer(@NotNull Enchantment enchantment, int enchantmentLevel, int cost) {
+    public EnchantmentOffer(final Enchantment enchantment, final int enchantmentLevel, final int cost) {
         this.enchantment = enchantment;
         this.enchantmentLevel = enchantmentLevel;
         this.cost = cost;
@@ -23,9 +31,8 @@ public class EnchantmentOffer {
      *
      * @return type of enchantment
      */
-    @NotNull
     public Enchantment getEnchantment() {
-        return enchantment;
+        return this.enchantment;
     }
 
     /**
@@ -33,7 +40,7 @@ public class EnchantmentOffer {
      *
      * @param enchantment type of the enchantment
      */
-    public void setEnchantment(@NotNull Enchantment enchantment) {
+    public void setEnchantment(final Enchantment enchantment) {
         Preconditions.checkArgument(enchantment != null, "The enchantment may not be null!");
 
         this.enchantment = enchantment;
@@ -45,7 +52,7 @@ public class EnchantmentOffer {
      * @return level of the enchantment
      */
     public int getEnchantmentLevel() {
-        return enchantmentLevel;
+        return this.enchantmentLevel;
     }
 
     /**
@@ -53,8 +60,8 @@ public class EnchantmentOffer {
      *
      * @param enchantmentLevel level of the enchantment
      */
-    public void setEnchantmentLevel(int enchantmentLevel) {
-        Preconditions.checkArgument(enchantmentLevel > 0, "The enchantment level must be greater than 0!");
+    public void setEnchantmentLevel(final @Positive int enchantmentLevel) {
+        requirePositive(enchantmentLevel, "enchantmentLevel");
 
         this.enchantmentLevel = enchantmentLevel;
     }
@@ -66,7 +73,7 @@ public class EnchantmentOffer {
      * @return cost for this enchantment
      */
     public int getCost() {
-        return cost;
+        return this.cost;
     }
 
     /**
@@ -75,9 +82,42 @@ public class EnchantmentOffer {
      *
      * @param cost cost for this enchantment
      */
-    public void setCost(int cost) {
-        Preconditions.checkArgument(cost > 0, "The cost must be greater than 0!");
+    public void setCost(final @Positive int cost) {
+        requirePositive(cost, "cost");
 
         this.cost = cost;
     }
+
+    @Override
+    public boolean equals(final @Nullable Object o) {
+        if (o == null || this.getClass() != o.getClass()) {
+            return false;
+        }
+        final EnchantmentOffer that = (EnchantmentOffer) o;
+        return this.getEnchantmentLevel() == that.getEnchantmentLevel() && this.getCost() == that.getCost() && Objects.equals(this.getEnchantment(), that.getEnchantment());
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.getEnchantment(), this.getEnchantmentLevel(), this.getCost());
+    }
+
+    /**
+     * Rolls a new set of enchantment offers based on a target item stack, a seed and a bookshelf count.
+     *
+     * @param targetStack    the itemstack for which the enchantment offers are rolled.
+     * @param seed           the seed used for random selection of enchantments.
+     *                       Mirrors {@link org.bukkit.inventory.view.EnchantmentView#getEnchantmentSeed()}.
+     * @param bookshelfCount the number of virtual bookshelves to consider when rolling the enchantments.
+     * @param offerAmount    the amount of enchantment offers to roll.
+     * @return an array of enchantment offers with size {@code offerAmount}.
+     */
+    public static @Nullable EnchantmentOffer[] rollEnchantmentOffers(
+        final ItemStack targetStack,
+        final int seed,
+        final int bookshelfCount,
+        final int offerAmount
+    ) {
+        return InternalAPIBridge.get().rollEnchantmentOffers(targetStack, seed, bookshelfCount, offerAmount);
+    }
 }

paper-api/src/main/java/org/bukkit/entity/AbstractArrow.java

@@ -173,8 +173,8 @@ public interface AbstractArrow extends Projectile {
      *
      * @return The firing ItemStack
      */
-    @Nullable // Paper
-    public ItemStack getWeapon();
+    @Override
+    @Nullable ItemStack getWeapon();
 
     /**
      * Sets the ItemStack which fired this arrow.

paper-api/src/main/java/org/bukkit/entity/Entity.java

@@ -1,16 +1,20 @@
 package org.bukkit.entity;
 
 import java.util.List;
+import java.util.Map;
 import java.util.Set;
 import java.util.UUID;
 import io.papermc.paper.datacomponent.DataComponentView;
 import io.papermc.paper.entity.LookAnchor;
 import io.papermc.paper.entity.RemovalReason;
 import io.papermc.paper.math.Angle;
+import java.util.function.Predicate;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.Namespaced;
 import net.kyori.adventure.text.event.HoverEvent;
 import net.kyori.adventure.text.event.HoverEventSource;
 import net.kyori.adventure.util.TriState;
-import org.bukkit.Chunk; // Paper
+import org.bukkit.Chunk;
 import org.bukkit.EntityEffect;
 import org.bukkit.Location;
 import org.bukkit.Material;
@@ -22,6 +26,8 @@ import org.bukkit.World;
 import org.bukkit.block.BlockFace;
 import org.bukkit.block.PistonMoveReaction;
 import org.bukkit.command.CommandSender;
+import org.bukkit.damage.DamageSource;
+import org.bukkit.damage.DamageType;
 import org.bukkit.event.entity.CreatureSpawnEvent;
 import org.bukkit.event.entity.EntityDamageEvent;
 import org.bukkit.event.entity.EntityRemoveEvent;
@@ -36,6 +42,7 @@ import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.UnmodifiableView;
 
 /**
  * Represents a base entity in the world
@@ -152,7 +159,6 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      */
     void setRotation(@NotNull Angle yaw, @NotNull Angle pitch);
 
-    // Paper start - Teleport API
     /**
      * Teleports this entity to the given location.
      * <p>
@@ -203,7 +209,6 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     default void lookAt(@NotNull io.papermc.paper.math.Position position, @NotNull LookAnchor entityAnchor) {
         this.lookAt(position.x(), position.y(), position.z(), entityAnchor);
     }
-    // Paper end - Teleport API
 
     /**
      * Teleports this entity to the given location.
@@ -259,7 +264,6 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      */
     public boolean teleport(@NotNull Entity destination, @NotNull TeleportCause cause);
 
-    // Paper start
     /**
      * Loads/Generates(in 1.13+) the Chunk asynchronously, and then teleports the entity when the chunk is ready.
      * <p>
@@ -325,7 +329,6 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @return A future that will be completed with the result of the teleport
      */
     java.util.concurrent.@NotNull CompletableFuture<Boolean> teleportAsync(@NotNull Location loc, @NotNull TeleportCause cause, @NotNull io.papermc.paper.entity.TeleportFlag @NotNull... teleportFlags);
-    // Paper end
 
     /**
      * Returns a list of entities within a bounding box centered around this
@@ -673,6 +676,17 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     @Nullable
     public EntityDamageEvent getLastDamageCause();
 
+    /**
+     * Gets the item being used as a weapon by this entity.
+     * <p>
+     * Note: In most cases this is the item in the entity's main hand, but
+     * it may be the offhand if for ex: the entity is using the riptide
+     * enchantment on a trident.
+     *
+     * @return The weapon item
+     */
+    @Nullable ItemStack getWeapon();
+
     /**
      * Returns a unique and persistent id for this entity
      *
@@ -866,19 +880,44 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     /**
      * Sets whether the entity is invulnerable or not.
      * <p>
-     * When an entity is invulnerable it can only be damaged by players in
+     * When an entity is invulnerable, it can only be damaged by players in
      * creative mode.
      *
      * @param flag if the entity is invulnerable
      */
-    public void setInvulnerable(boolean flag);
+    void setInvulnerable(boolean flag);
 
     /**
-     * Gets whether the entity is invulnerable or not.
+     * Gets the current invulnerability state of the entity set by {@link #setInvulnerable(boolean)}.
      *
-     * @return whether the entity is
+     * @return whether the entity is invulnerable
+     * @see #isInvulnerableTo(DamageSource)
      */
-    public boolean isInvulnerable();
+    boolean isMarkedInvulnerable();
+
+    /**
+     * Determines if the entity is invulnerable to the specified damage source.
+     * <p>
+     * Using this method with {@code DamageSource.builder(DamageType.GENERIC).build()} is equivalent to {@link #isInvulnerable()}
+     *
+     * @param source the damage source to check against
+     * @return {@code true} if the entity is invulnerable to the given damage source, {@code false} otherwise
+     */
+    boolean isInvulnerableTo(@NotNull DamageSource source);
+
+    /**
+     * Gets whether the entity is invulnerable or not
+     *
+     * @return whether the entity is invulnerable
+     * @see #isInvulnerableTo(DamageSource)
+     * @deprecated This method does not reflect the invulnerability state set by
+     *   {@link #setInvulnerable(boolean)}, use {@link #isMarkedInvulnerable()} for that instead.
+     *   Use {@link #isInvulnerableTo(DamageSource)} with {@code DamageSource.builder(DamageType.GENERIC).build()} as a direct replacement to this method.
+     */
+    @Deprecated(since = "26.3")
+    default boolean isInvulnerable() {
+        return this.isInvulnerableTo(DamageSource.builder(DamageType.GENERIC).build());
+    }
 
     /**
      * Gets whether the entity is silent or not.
@@ -910,6 +949,27 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      */
     void setGravity(boolean gravity);
 
+    /**
+     * Returns the default acceleration due to gravity (in blocks per tick). Ignores {@link Entity#hasGravity()}.
+     *
+     * @return the default acceleration due to gravity
+     */
+    double getDefaultGravity();
+
+    /**
+     * Returns the acceleration due to gravity (in blocks per tick). If {@link Entity#hasGravity()} is false, returns 0.
+     *
+     * @return the acceleration due to gravity
+     */
+    double getGravity();
+
+    /**
+     * Returns the air drag factor applied to this entity.
+     *
+     * @return the air drag factor
+     */
+    float getAirDrag();
+
     /**
      * Gets the period of time (in ticks) before this entity can use a portal.
      *
@@ -989,7 +1049,6 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     @NotNull
     Pose getPose();
 
-    // Paper start
     /**
      * Returns if the entity is in sneak mode
      *
@@ -1042,7 +1101,6 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @return whether the entity has a fixed {@link Pose}
      */
     boolean hasFixedPose();
-    // Paper end
 
     /**
      * Get the category of spawn to which this entity belongs.
@@ -1102,7 +1160,6 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     @ApiStatus.Experimental
     Entity copy(@NotNull Location to);
 
-    // Spigot start
     public class Spigot extends CommandSender.Spigot {
 
     }
@@ -1110,9 +1167,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     @NotNull
     @Override
     Spigot spigot();
-    // Spigot end
 
-    // Paper start
     /**
      * Gets the entity's display name formatted with their team prefix/suffix and
      * the entity's default hover/click events.
@@ -1301,9 +1356,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @return the entity's yaw
      */
     float getYaw();
-    // Paper end
 
-    // Paper start - Collision API
     /**
      * Checks for any collisions with the entity's bounding box at the provided location.
      * This will check for any colliding entities (boats, shulkers) / worldborder / blocks.
@@ -1323,20 +1376,16 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @return collides or not
      */
     boolean wouldCollideUsing(@NotNull BoundingBox boundingBox);
-    // Paper end - Collision API
 
-    // Paper start - Folia schedulers
     /**
      * Returns the task scheduler for this entity. The entity scheduler can be used to schedule tasks
      * that are guaranteed to always execute on the tick thread that owns the entity.
-     * <p><b>If you do not need/want to make your plugin run on Folia, use {@link org.bukkit.Server#getScheduler()} instead.</b></p>
+     *
      * @return the task scheduler for this entity.
      * @see io.papermc.paper.threadedregions.scheduler.EntityScheduler
      */
     @NotNull io.papermc.paper.threadedregions.scheduler.EntityScheduler getScheduler();
-    // Paper end - Folia schedulers
 
-    // Paper start - entity scoreboard name
     /**
      * Gets the string name of the entity used to track it in {@link org.bukkit.scoreboard.Scoreboard Scoreboards}.
      *
@@ -1345,9 +1394,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @see org.bukkit.scoreboard.Scoreboard#getEntries()
      */
     @NotNull String getScoreboardEntryName();
-    // Paper end - entity scoreboard name
 
-    // Paper start - broadcast hurt animation
     /**
      * Broadcasts a hurt animation. This fakes incoming damage towards the target entity.
      * <p>
@@ -1358,5 +1405,49 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @throws IllegalArgumentException if {@code this} is contained in {@code players}
      */
     void broadcastHurtAnimation(@NotNull java.util.Collection<Player> players);
-    // Paper end - broadcast hurt animation
+
+    /**
+     * Gets if the entity is allied to the given entity.
+     *
+     * @param other the other entity
+     * @return {@code true} if the entity is allied to the given entity
+     */
+    boolean isAlliedTo(@NotNull Entity other);
+
+    /**
+     * Gets an immutable map of the current additional rules of alliance with any entity.
+     * <br>
+     * These are additional rules from the vanilla behavior for any entity, like share a team.
+     * <br>
+     * These rules are not (currently) persistent.
+     *
+     * @return an immutable map of the current additional rules of alliance with any entity
+     * @see #addAdditionalAlliedRule(Key, Predicate)
+     */
+    @UnmodifiableView
+    @NotNull Map<Key, Predicate<Entity>> getAdditionalAlliedRules();
+
+    /**
+     * Add a rule of alliance with any entity.
+     * <br>
+     * If a rule with the specified {@link Key} already exists, it will be overwritten.
+     *
+     * @param key the key of the rule
+     * @param predicate the rule of alliance with any entity
+     */
+    void addAdditionalAlliedRule(@NotNull Key key, @NotNull Predicate<Entity> predicate);
+
+    /**
+     * Remove the rule of alliance with any entity.
+     *
+     * @param key the key of the rule
+     */
+    void removeAdditionalAlliedRule(@NotNull Key key);
+
+    /**
+     * Remove the rules of alliance with any entity.
+     *
+     * @param namespaced the namespaced of the rule
+     */
+    void removeAdditionalAlliedRule(@NotNull Namespaced namespaced);
 }

paper-api/src/main/java/org/bukkit/entity/HumanEntity.java

@@ -536,6 +536,17 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      */
     public void startRiptideAttack(int duration, float attackStrength, @Nullable ItemStack attackItem);
 
+    /**
+     * Check if the player can critical attack the target {@link Entity}.
+     * <br>
+     * Note: When hitting an entity, Minecraft also checks that the result of {@link #getAttackCooldown()} is {@code > 0.9F}
+     * to determine if the critical attack will happen.
+     *
+     * @param entity target entity to check if can critical attack
+     * @return whether they can critical attack the target entity
+     */
+    public boolean canCriticalAttack(Entity entity);
+
     /**
      * Gets the location of the bed the player is currently sleeping in
      *
@@ -981,7 +992,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
     public int getStarvationRate();
 
     /**
-     * Get the starvation rate (1 health per x ticks) of
+     * Set the starvation rate (1 health per x ticks) of
      * the HumanEntity. Default is 80.
      *
      * @param ticks the amount of ticks to lose 1 health

paper-api/src/main/java/org/bukkit/entity/LivingEntity.java

@@ -1,5 +1,6 @@
 package org.bukkit.entity;
 
+import com.google.common.base.Preconditions;
 import java.util.Collection;
 import java.util.List;
 import java.util.Set;
@@ -1401,25 +1402,39 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
     void setHurtDirection(float hurtDirection);
     // Paper end - hurt direction API
 
-    // Paper start - swing hand API
     /**
-     * Makes this entity swing their hand.
+     * Makes this entity swing their hand, using the {@link io.papermc.paper.datacomponent.DataComponentTypes#ATTACK_ANIMATION}
+     * component on the item held in that hand to determine the animation type and duration.
+     * If the held item does not have the component, the default {@link io.papermc.paper.datacomponent.item.SwingAnimation.Animation#WHACK}
+     * animation with a duration of {@code 6} ticks is used.
      *
      * <p>This method does nothing if this entity does not
      * have an animation for swinging their hand.
      *
      * @param hand hand to be swung, either {@link org.bukkit.inventory.EquipmentSlot#HAND} or {@link org.bukkit.inventory.EquipmentSlot#OFF_HAND}
-     * @throws IllegalArgumentException if invalid hand is passed
+     * @throws IllegalArgumentException if an invalid hand is passed
      */
     default void swingHand(@NotNull org.bukkit.inventory.EquipmentSlot hand) {
-        com.google.common.base.Preconditions.checkArgument(hand != null && hand.isHand(), String.format("Expected a valid hand, got \"%s\" instead!", hand));
+        Preconditions.checkArgument(hand != null && hand.isHand(), "Expected a valid hand, got \"%s\" instead!", hand);
         if (hand == org.bukkit.inventory.EquipmentSlot.HAND) {
             this.swingMainHand();
         } else {
             this.swingOffHand();
         }
     }
-    // Paper end - swing hand API
+
+    /**
+     * Makes this entity swing their hand using the provided {@link io.papermc.paper.datacomponent.item.SwingAnimation},
+     * instead of the swing animation component the held item may have.
+     *
+     * <p>This method does nothing if this entity does not
+     * have an animation for swinging their hand.
+     *
+     * @param hand hand to be swung, either {@link org.bukkit.inventory.EquipmentSlot#HAND} or {@link org.bukkit.inventory.EquipmentSlot#OFF_HAND}
+     * @param swingAnimation the swing animation to use
+     * @throws IllegalArgumentException if an invalid hand is passed
+     */
+    void swingHand(@NotNull org.bukkit.inventory.EquipmentSlot hand, @NotNull io.papermc.paper.datacomponent.item.SwingAnimation swingAnimation);
 
     // Paper start - knockback API
     /**

paper-api/src/main/java/org/bukkit/entity/Mob.java

@@ -33,9 +33,7 @@ public interface Mob extends LivingEntity, Lootable, Leashable {
      * </ul>
      *
      * @param state a TriState representing the state of the override
-     * @deprecated the client no longer allows to change that setting and will not render the entity
      */
-    @Deprecated(since = "26.2")
     void setDespawnInPeacefulOverride(TriState state);
 
     /**
@@ -48,9 +46,7 @@ public interface Mob extends LivingEntity, Lootable, Leashable {
      *
      * @return a TriState representing the state of the override
      * @see Mob#setDespawnInPeacefulOverride(TriState)
-     * @deprecated the client no longer allows to change that setting and will not render the entity
      */
-    @Deprecated(since = "26.2")
     TriState getDespawnInPeacefulOverride();
 
     @Override

paper-api/src/main/java/org/bukkit/entity/Player.java

@@ -5,10 +5,12 @@ import com.google.common.base.Preconditions;
 import io.papermc.paper.connection.PlayerGameConnection;
 import io.papermc.paper.entity.LookAnchor;
 import io.papermc.paper.entity.PlayerGiveResult;
+import io.papermc.paper.entity.PlayerPostEffects;
 import io.papermc.paper.math.Angle;
 import io.papermc.paper.math.Position;
 import java.net.InetAddress;
 import java.net.InetSocketAddress;
+import java.net.SocketAddress;
 import java.time.Duration;
 import java.time.Instant;
 import java.util.Collection;
@@ -274,7 +276,17 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @return the player's address
      */
     @Nullable
-    public InetSocketAddress getAddress();
+    SocketAddress getSocketAddress();
+
+    /**
+     * Returns an instance of {@link InetSocketAddress} associated with the
+     * player's socket address.
+     *
+     * @return the player's {@link InetSocketAddress}, or the loopback address
+     * if the player is connecting through a Unix domain socket
+     */
+    @Nullable
+    InetSocketAddress getAddress();
 
     // Paper start - Add API to get player's proxy address
     /**
@@ -4076,4 +4088,11 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * clearing any fixed pose in the process.
      */
     void unsetFixedPose();
+
+    /**
+     * Gets the post-effects that can be applied to this player.
+     *
+     * @return the post-effects
+     */
+    PlayerPostEffects postEffects();
 }

paper-api/src/main/java/org/bukkit/entity/SulfurCube.java

@@ -1,12 +1,17 @@
 package org.bukkit.entity;
 
+import com.destroystokyo.paper.event.entity.EntityAddToWorldEvent;
 import io.papermc.paper.entity.Bucketable;
 import io.papermc.paper.entity.Shearable;
+import io.papermc.paper.event.entity.EntityEquipmentChangedEvent;
 import io.papermc.paper.registry.RegistryAccess;
 import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.keys.tags.ItemTypeTagKeys;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.key.KeyPattern;
 import org.bukkit.Keyed;
+import org.bukkit.inventory.EquipmentSlot;
+import org.bukkit.inventory.ItemStack;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -73,6 +78,58 @@ public interface SulfurCube extends AbstractCubeMob, Shearable, Bucketable, Agea
         return this.ignite(false);
     }
 
+    /**
+     * Makes this sulfur cube swallow the provided item, following any Vanilla logic.
+     * <p>
+     * This method will:
+     * <ul>
+     *     <li>not equip the item to a baby sulfur cube,</li>
+     *     <li>if present, drop a previously swallowed item, and</li>
+     *     <li>play the swallow sound.</li>
+     * </ul>
+     * <p>
+     * If the currently swallowed item is changed, a {@link EntityEquipmentChangedEvent} is called.
+     * May also call a {@link EntityAddToWorldEvent} for the newly dropped {@link Item} entity.
+     *
+     * @param itemStack the item to swallow. Use {@link ItemStack#empty()} to unset the item.
+     *                  Items not in the {@link ItemTypeTagKeys#SULFUR_CUBE_SWALLOWABLE} tag
+     *                  will not be properly rendered inside the sulfur cube
+     * @return whether the sulfur cube's absorbed item was updated
+     * @see #setEquipped(ItemStack) set the swallowed item, skipping any Vanilla swallow logic
+     */
+    boolean swallow(ItemStack itemStack);
+
+    /**
+     * Sets the swallowed item stack for this sulfur cube.
+     * <p>
+     * This method acts as a simple utility method to set the {@link EquipmentSlot#BODY}
+     * equipment slot of this sulfur cube, which holds the sulfur cube's swallowed item.
+     * <p>
+     * Different to {@link #swallow(ItemStack)}, this method does not play a sound or
+     * drop the previously equipped item on the ground.
+     * <p>
+     * This method will call a {@link EntityEquipmentChangedEvent}.
+     *
+     * @param itemStack the item stack to be equipped, use {@link ItemStack#empty()} to unset the item
+     * @see #swallow(ItemStack) set the swallowed item, following any Vanilla swallow logic
+     */
+    default void setEquipped(final ItemStack itemStack) {
+        this.getEquipment().setItem(EquipmentSlot.BODY, itemStack);
+    }
+
+    /**
+     * Retrieves the item stack currently swallowed by this sulfur cube.
+     * <p>
+     * This method acts as a simple utility method to get the {@link EquipmentSlot#BODY}
+     * equipment slot of this sulfur cube, which holds the sulfur cube's swallowed item.
+     *
+     * @return the item stack in the {@link EquipmentSlot#BODY} equipment slot, returns {@link ItemStack#empty()}
+     * if no item is present
+     */
+    default ItemStack getEquipped() {
+        return this.getEquipment().getItem(EquipmentSlot.BODY);
+    }
+
     /**
      * Represents the archetype of a sulfur cube
      * which define a lot of possible behavior and interaction

paper-api/src/main/java/org/bukkit/event/HandlerList.java

@@ -206,6 +206,13 @@ public class HandlerList {
         return handlers;
     }
 
+    /**
+     * {@return whether this handler list has any listeners}
+     */
+    public boolean hasListeners() {
+        return this.getRegisteredListeners().length != 0;
+    }
+
     /**
      * Get a specific plugin's registered listeners associated with this
      * handler list

paper-api/src/main/java/org/bukkit/event/entity/EntityCreatePortalEvent.java

@@ -2,6 +2,7 @@ package org.bukkit.event.entity;
 
 import java.util.List;
 import org.bukkit.PortalType;
+import org.bukkit.Warning;
 import org.bukkit.block.BlockState;
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.event.Cancellable;
@@ -16,6 +17,7 @@ import org.jetbrains.annotations.NotNull;
  * @deprecated Use {@link PortalCreateEvent}
  */
 @Deprecated(since = "1.14.1")
+@Warning(propagate = false)
 public class EntityCreatePortalEvent extends EntityEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/org/bukkit/event/entity/EntityKnockbackByEntityEvent.java

@@ -1,5 +1,6 @@
 package org.bukkit.event.entity;
 
+import org.bukkit.Warning;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.util.Vector;
@@ -12,6 +13,7 @@ import org.jetbrains.annotations.NotNull;
  * @deprecated use {@link com.destroystokyo.paper.event.entity.EntityKnockbackByEntityEvent}
  */
 @Deprecated(forRemoval = true) // Paper
+@Warning(propagate = false)
 public class EntityKnockbackByEntityEvent extends EntityKnockbackEvent {
 
     private final Entity source;

paper-api/src/main/java/org/bukkit/event/entity/EntityKnockbackEvent.java

@@ -1,6 +1,7 @@
 package org.bukkit.event.entity;
 
 import com.google.common.base.Preconditions;
+import org.bukkit.Warning;
 import org.bukkit.attribute.Attribute;
 import org.bukkit.enchantments.Enchantment;
 import org.bukkit.entity.LivingEntity;
@@ -16,6 +17,7 @@ import org.jetbrains.annotations.NotNull;
  * @deprecated use {@link io.papermc.paper.event.entity.EntityKnockbackEvent}
  */
 @Deprecated(forRemoval = true) // Paper
+@Warning(propagate = false)
 public class EntityKnockbackEvent extends EntityEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();