BlueGit

timfa birdcourier

Files

birdcourier
README.md

BirdCourier 1.1.3

Paper 26.2 plugin that sends the item stack in your hand to another online player with a flying courier mob.

Requirements

  • Paper 26.2 (Java 25)
  • No other plugins required

Install

1. Build the plugin (see Build) or take the BirdCourier-<version>.jar from a BlueGit pipeline artifact. 2. Place the jar in the server plugins/ folder. 3. Start or restart the Paper server. 4. Optional: edit plugins/BirdCourier/config.yml, then run /birdcourier reload.

Playing

1. Hold the stack you want to send in your main hand. 2. Run /send <player>. The other player must be online; you cannot send to yourself. 3. A courier spawns near you and flies to the recipient (including through unloaded chunks, and through Nether/End portals when enabled). 4. On arrival the stack is delivered into the recipient's inventory. If nobody can receive it, the courier returns or the shipment is lost after the configured wait.

Pick a personal courier with /courier <type> (tab completion). The choice is stored per player in plugins/BirdCourier/couriers.properties. If you have not chosen one, the default from visual.entity-type is used (parrot).

Allowed types: allay, bat, bee, blaze, chicken, baby_chicken, ghast, parrot, vex.

  • ghast uses a baby HAPPY_GHAST (Ghastling).
  • Visual mobs with a usable main-hand equipment slot show a visual copy of the shipment item.
  • Bats are kept awake so they do not hang upside down mid-flight.

Commands

CommandPermissionDefaultDescription
/send <player>birdcourier.sendeveryoneSend the held stack to an online player.
/courier <type>birdcourier.couriereveryoneSet your personal courier mob.
/birdcourier statusbirdcourier.adminopShow the number of active shipments.
/birdcourier reloadbirdcourier.adminopReload config.yml.

Configuration

Defaults live in config.yml (copied to plugins/BirdCourier/ on first run):

  • visual — default entity type (PARROT) and whether the courier is silent
  • flight — visible speed (default 10 blocks/s), unloaded-chunk speed multiplier (5×), preferred height (10), direct-approach distance (15), delivery range, pathfinding limits
  • unreachable — how long to wait and retry when the recipient cannot be reached
  • portals — follow Nether/End portals (enabled by default)
  • persistence — autosave interval for shipments.tsv
  • messages — player-facing chat text
  • cleanup — delayed cleanup of leftover courier visuals after chunk load; BirdCourier tags are authoritative, so ordinary invulnerable or no-gravity mobs are not removed

Active shipments are stored in plugins/BirdCourier/shipments.tsv. Courier choices are stored in plugins/BirdCourier/couriers.properties.

Build

The project targets the official Paper 26.2 API build 26.2.build.112-stable and Java 25.

With Gradle installed:

gradle build

The resulting JAR is build/libs/BirdCourier-<version>.jar.

Run the unit tests with:

gradle test

Releases

On BlueGit, a master push runs the tests and builds the jar (no manual job). Push a version tag (for example 1.1.4 or v1.1.4) to publish a release automatically: the pipeline runs the tests, builds the jar, and attaches BirdCourier-<version>.jar to the tag. A leading v on the tag is stripped from the version and file name.

Changelog

1.1.3

  • Cleanup no longer removes legitimate courier-capable mobs merely for being invulnerable or gravity-disabled.
  • Legacy ghost fallback now requires AI to be explicitly disabled.
  • BirdCourier tags remain authoritative for cleanup.

1.1.2

  • Phantom removed; chicken and baby_chicken added; bats forced awake.

1.1.1 / 1.1.0

  • Adds /courier <type> with tab completion for allay, bat, bee, blaze, ghast, parrot, phantom and vex (phantom later removed in 1.1.2).
  • Courier choice is stored per player in couriers.properties.
  • ghast uses a baby HAPPY_GHAST (Ghastling).
  • Visual mobs with a usable main-hand equipment slot receive a visual copy of the shipment item.

1.0.15

  • Default visible speed: 10 blocks/second.
  • Default unloaded travel multiplier: 5x.
  • Default preferred flight height: 10 blocks.
  • Default direct-approach distance: 15 blocks.
  • Visual courier entities are non-persistent, so they are not saved into chunk data and later return as ghosts.